> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lambdadb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration CLI

> Use the LambdaDB Migration CLI to move vector search workloads from existing systems into LambdaDB.

The recommended path for moving existing vector search workloads to LambdaDB is the LambdaDB Migration CLI.

The CLI inventories the source system, generates an editable LambdaDB mapping, creates the target collection when needed, streams records into LambdaDB, saves local checkpoints, and can validate migrated documents before cutover.

## Supported sources

For PostgreSQL applications, see [Search with PostgreSQL and LambdaDB](https://docs.lambdadb.ai/guides/migrations/postgresql/search-with-postgresql.md) for collection design, search compatibility, and application-owned ingestion. PostgreSQL is not currently a Migration CLI source.

| Source | Status | Notes |
| :- | :- | :- |
| Qdrant | Supported | Dense vectors, named dense vectors, sparse vectors, payload indexes, local checkpoints, validation reports, and dense/sparse-vector query overlap checks. |
| Pinecone Serverless | Supported | Dense indexes, sparse indexes, namespaces, ID-prefix scoped migrations, metadata payloads, local checkpoints, validation reports, and dense/sparse-vector query overlap checks. |
| Elasticsearch | Supported | Index mappings, scalar/text fields, dense vectors, PIT/search\_after reads, local checkpoints, and validation reports. Query-overlap validation is not implemented for Elasticsearch yet. |
| OpenSearch | Planned | Use the same CLI workflow once OpenSearch support is available. |
| Chroma | Planned | Use the same CLI workflow once Chroma support is available. |
| Weaviate | Planned | Use the same CLI workflow once Weaviate support is available. |

The CLI validates and forwards all 49 [fixed analyzer presets](https://docs.lambdadb.ai/guides/collections/choose-text-analyzers.md). Elasticsearch inventory preserves supported field analyzers and index defaults, and flags custom or unsupported settings for explicit review. Verification searches retain their dense/sparse behavior and do not rerank. See [Elasticsearch analyzer mappings](https://docs.lambdadb.ai/guides/migrations/elasticsearch/migrate-from-elasticsearch.md#text-analyzer-presets).

## Migration workflow

1. Install the CLI.
2. Generate an inventory and editable mapping from the source.
3. Review the generated LambdaDB collection and field mapping.
4. Run a dry run.
5. Run the migration with validation enabled.
6. Review the validation report and representative search results.
7. Switch production traffic after result quality, latency, and application query rewrites are verified.

## Install the CLI

This guide covers [**v0.1.9**](https://github.com/lambdadb/lambdadb-migration/releases/tag/v0.1.9). Install the latest stable release below. The executable is `lambdadb-migration`; the [general LambdaDB CLI](https://docs.lambdadb.ai/guides/get-started/use-with-cli.md) uses `lambdadb` for JSONL imports and everyday queries.

> [tab] Homebrew
>
> With [Homebrew](https://brew.sh/) on macOS or Linux:
>
> ```bash theme={null}
> brew install lambdadb/tap/lambdadb-migration
> lambdadb-migration --version
> lambdadb-migration --help
> ```
>
> The [public tap](https://github.com/lambdadb/homebrew-tap) installs the released binary without Go or Node. To update:
>
> ```bash theme={null}
> brew update
> brew upgrade lambdadb/tap/lambdadb-migration
> ```
>
> To remove the binary:
>
> ```bash theme={null}
> brew uninstall lambdadb/tap/lambdadb-migration
> ```
>
> New GitHub releases may reach the tap later, after the formula is updated.

> [tab] Standalone installer
>
> Download the release-tagged installer to a scratch directory and inspect it before running. This example pins the installer and selects the latest release binary:
>
> ```bash theme={null}
> curl -fsSLo install.sh https://raw.githubusercontent.com/lambdadb/lambdadb-migration/v0.1.9/install.sh
> less install.sh
> sh install.sh --version latest --install-dir "$HOME/.local/bin"
> export PATH="$HOME/.local/bin:$PATH"
> lambdadb-migration --version
> lambdadb-migration --help
> ```
>
> The installer checks the release archive against `checksums.txt`. It requires `curl`, `tar`, and `sha256sum` or `shasum`. No Go or Node runtime is required. Without `--install-dir`, it uses `/usr/local/bin` and may request `sudo`.
>
> Run the same commands to update. For a reproducible binary version, pass `--version v0.1.9`; choose an installer tag and binary version suitable for your workflow.
>
> To remove a standalone installation, use its original directory:
>
> ```bash theme={null}
> sh install.sh --uninstall --install-dir "$HOME/.local/bin"
> ```

Release binaries are available for **macOS and Linux, amd64 and arm64**. Windows binaries are not provided. Choose the archive matching your operating system and architecture when downloading a binary directly from the [releases page](https://github.com/lambdadb/lambdadb-migration/releases).

Before switching installation methods, inspect `type -a lambdadb-migration` and identify which binary is on PATH. Remove only the old installation using its original method. Do not force-overwrite a Homebrew symlink or run the standalone installer against a Homebrew-managed path. Uninstalling the binary does not remove mappings, checkpoints, or credentials.

## Common CLI behavior

> [!NOTE]
>
> LambdaDB Cloud uses region-specific API base URLs. Use your project's **base URL** and **project name**, together with a **project API key** created in its **API Keys** tab. Project creation does not automatically issue a key; save the full value when you create it, because it is shown only once. See [API key management](https://docs.lambdadb.ai/guides/get-started/quickstart.md#manage-api-keys). Do not assume a global default URL or a fixed project name.

Set these values before running migration commands:

```bash theme={null}
export LAMBDADB_BASE_URL="YOUR_REGION_BASE_URL"
export LAMBDADB_PROJECT_NAME="YOUR_PROJECT_NAME"
export LAMBDADB_PROJECT_API_KEY="YOUR_PROJECT_API_KEY"
```

The migration executable reads these environment variables or its own command flags. It does not load `.env` files or the general CLI's saved configuration.

Generated mappings set `target.createCollection: true` by default. With that setting, the migration creates the LambdaDB collection if it does not already exist, then begins writing documents. The CLI does not poll a collection status; transient write failures use its retry policy.

Use `--migration.create-collection=false` when the LambdaDB collection already exists and the migration should fail instead of creating it.

The CLI stores local checkpoints under `.lambdadb-migration/checkpoints` by default. If a migration is interrupted, rerun the same command to resume from the last saved checkpoint. Use `--migration.restart` to start from the beginning.

A completed checkpoint skips re-reading and uploading documents on rerun. Use `--migration.restart` to migrate new source data after a completed run. Validation-enabled runs retain sample documents in local checkpoint files so validation can be retried without uploading again; protect these files as source data. If a completed checkpoint has no saved samples, restart to collect them or use `--migration.validation-sample-size=0` for count-only validation.

## Generate embeddings from migrated text

The Migration CLI supports explicit [native embedding configuration](https://docs.lambdadb.ai/guides/collections/native-embeddings.md) under `payload.indexConfigs`. Merge the following settings into the `payload` section of your generated JSON or YAML mapping, preserving its other source, target, and vector settings. This example renames source text `source_body` to `body` and adds a separate generated vector field:

```yaml theme={null}
payload:
  mode: flatten
  rename:
    source_body: body
  indexConfigs:
    body:
      type: text
    generated_vector:
      type: vector
      embedding:
        provider: openai
        model: text-embedding-3-small
        sources:
          - field: body
            type: text
```

Each `sources` entry names a destination field after renaming; dotted paths select values inside stored objects. OpenAI models take exactly one text source. A Cohere model combines up to 16 text and image sources, where an image field holds a public HTTPS URL or data URI, or a flat array of them:

```yaml theme={null}
payload:
  indexConfigs:
    generated_vector:
      type: vector
      embedding:
        provider: cohere
        model: embed-v5.0-fast
        dimensions: 1024
        sources:
          - field: body
            type: text
          - field: image_url
            type: image
```

Put explicit `dimensions` and `similarity` inside `embedding`; the CLI inserts no defaults and rejects top-level native `dimensions`/`similarity`, `embedding.dimensions` outside the [supported range](https://docs.lambdadb.ai/guides/get-started/limits.md#collections-and-schema), and unknown keys in a `sources` entry during mapping validation. Model, source type, and image limits remain server validations.

Set `--migration.write-mode upsert`: bulk upsert never generates embeddings. Generation consumes inference usage, including possible repeated provider calls on retries.

Generated inventories preserve stored vectors as ordinary vector fields. Keep those fields separate from generated vectors; a native payload index cannot replace a mapped source vector field. Existing target schemas are not updated or reconciled.

Query-overlap validation continues to use stored dense/sparse vectors. It does not run Bayesian queries, rerank results, or measure generated-vector quality.

## Validation

Use `--migration.validate` for post-migration checks. Validation compares the accepted record count against the source inventory, fetches a sample of migrated documents from LambdaDB with strongly consistent reads, and compares sampled fields.

Use `--migration.validation-report` to write a JSON report:

```bash theme={null}
--migration.validate \
--migration.validation-report validation-report.json
```

For Qdrant and Pinecone vector migrations, `--migration.query-overlap` compares source and LambdaDB nearest-neighbor results for validation samples. By default, it reports overlap without failing the migration. Set `--migration.query-overlap-min-ratio` above `0` to require a minimum average overlap. Query-overlap validation is not implemented for Elasticsearch yet.

## Next steps

> [card] [Search with PostgreSQL](https://docs.lambdadb.ai/guides/migrations/postgresql/search-with-postgresql.md)
>
> Organize tenant, chat, and repository search datasets and review PostgreSQL search compatibility.

> [card] [Migrate from Qdrant](https://docs.lambdadb.ai/guides/migrations/qdrant/migrate-from-qdrant.md)
>
> Move Qdrant collections, points, vectors, sparse vectors, and payload indexes to LambdaDB.

> [card] [Migrate from Pinecone](https://docs.lambdadb.ai/guides/migrations/pinecone/migrate-from-pinecone.md)
>
> Move Pinecone Serverless indexes, namespaces, vectors, and metadata to LambdaDB.

> [card] [Migrate from Elasticsearch](https://docs.lambdadb.ai/guides/migrations/elasticsearch/migrate-from-elasticsearch.md)
>
> Move Elasticsearch index mappings, documents, and dense vectors to LambdaDB.

> [card] [Create a collection](https://docs.lambdadb.ai/guides/collections/create-a-collection.md)
>
> Learn how LambdaDB collection index configurations map to migrated data.

> [card] [Bulk upsert data](https://docs.lambdadb.ai/guides/documents/bulk-upsert-data.md)
>
> Understand LambdaDB bulk loading behavior for collections with caller-provided vectors.

> [card] [Hybrid query](https://docs.lambdadb.ai/guides/search/hybrid.md)
>
> Rewrite dense, sparse, and lexical hybrid search after migration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.