Create a new collection

This page shows you how to create a collection with various configurations.

Parameters

Parameter	Type	Required	Description
collectionName	string	✓	Unique name within the project; 3 to 52 letters, numbers, underscores, or hyphens
indexConfigs	object	✓	Nonempty field configuration for indexing
description	string		Collection description, up to 255 characters
tags	object		Up to five metadata key-value pairs
partitionConfig	object		Partition configuration
snapshotRetentionInDays	integer		Snapshot retention from 1 through 31 days; defaults to 30

Create a collection from scratch

The simplest way to create a collection is to provide the collection name and the field index configurations. These examples explicitly select Japanese, Korean, and English analyzers for content. Select the analyzers that fit your data using Choose text analyzers; omitting analyzers uses ["standard"].

from lambdadb import LambdaDB, models

with LambdaDB(
    project_api_key="YOUR_API_KEY",
    base_url="YOUR_BASE_URL",
    project_name="YOUR_PROJECT_NAME",
) as client:
    basic_config = {
        "url": {"type": "keyword"},
        "author": {"type": "keyword"},
        "content": {
            "type": "text",
            "analyzers": ["japanese", "korean", "english"],
        },
    }
    client.collections.create(collection_name="example-collection", index_configs=basic_config)

Python: LambdaDB supports context manager usage. __enter__ returns the client, and __exit__ calls client.close() (closing the SDK-owned HTTP client) and makes the client unusable after the with block. If you don’t use with, call client.close() when you’re done. If you pass a custom client=/async_client=, you own closing it.

import { LambdaDBClient } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({
  projectApiKey: "YOUR_API_KEY",
  baseUrl: "YOUR_BASE_URL",
  projectName: "YOUR_PROJECT_NAME",
});
await client.createCollection({
  collectionName: "example-collection",
  indexConfigs: {
    url: { type: "keyword" },
    author: { type: "keyword" },
    content: { type: "text", analyzers: ["japanese", "korean", "english"] },
  },
});

package main

import (
  "context"
  "log"

  lambdadb "github.com/lambdadb/go-lambdadb"
  "github.com/lambdadb/go-lambdadb/models/components"
)

func main() {
  ctx := context.Background()
  client := lambdadb.New(
    lambdadb.WithBaseURL("YOUR_BASE_URL"),
    lambdadb.WithProjectName("YOUR_PROJECT_NAME"),
    lambdadb.WithAPIKey("YOUR_API_KEY"),
  )
  _, err := client.Collections.Create(ctx, lambdadb.CreateCollectionOptions{
    CollectionName: "example-collection",
    IndexConfigs: map[string]components.IndexConfigsUnion{
      "url": components.CreateIndexConfigsUnionKeyword(components.IndexConfigs{Type: components.TypeKeyword}),
      "author": components.CreateIndexConfigsUnionKeyword(components.IndexConfigs{Type: components.TypeKeyword}),
      "content": components.CreateIndexConfigsUnionText(components.IndexConfigsText{
        Type: components.TypeTextText,
        Analyzers: []components.Analyzer{components.AnalyzerJapanese, components.AnalyzerKorean, components.AnalyzerEnglish},
      }),
    },
  })
  if err != nil {
    log.Fatal(err)
  }
}

LAMBDADB_PROJECT_API_KEY="YOUR_API_KEY"

curl -i -X POST "$BASE_URL/projects/$PROJECT_NAME/collections" \
  -H "content-type: application/json" \
  -H "x-api-key: $LAMBDADB_PROJECT_API_KEY" \
  -d '{
        "collectionName": "example-collection",
        "description": "Articles searchable by URL, author, and content",
        "tags": { "environment": "production" },
        "snapshotRetentionInDays": 30,
        "indexConfigs": {
          "url": { "type": "keyword" },
          "author": { "type": "keyword" },
          "content": { "type": "text", "analyzers": ["japanese", "korean", "english"] }
        }
      }'

A successful REST request returns 201 Created. Collection creation also creates the default branch, main:

{
  "collection": {
    "collectionName": "example-collection",
    "description": "Articles searchable by URL, author, and content",
    "tags": { "environment": "production" },
    "defaultBranchName": "main",
    "snapshotRetentionInDays": 30,
    "createdAt": 1788336000000
  }
}

Collection and ref timestamps, including source.asOf, use numeric Unix epoch milliseconds. The create response is intentionally compact. Use describe or list to retrieve indexConfigs, document counts, and the full collection model. 201 confirms catalog creation; it does not guarantee query-serving readiness or completed indexing. Handle loading and retry states using actual operations; there is no collection-status readiness field to poll.

Create a collection with native embeddings

Native embeddings let LambdaDB derive vector values from a source text field. Define the vector field with an embedding block. The source field must be a text field in the same collection. For supported models and configuration rules, see Native embeddings.

from lambdadb import LambdaDB

with LambdaDB(
    project_api_key="YOUR_API_KEY",
    base_url="YOUR_BASE_URL",
    project_name="YOUR_PROJECT_NAME",
) as client:
    client.collections.create(
        collection_name="semantic-docs",
        index_configs={
            "body": {
                "type": "text",
                "analyzers": ["english"],
            },
            "bodyEmbedding": {
                "type": "vector",
                "embedding": {
                    "provider": "openai",
                    "model": "text-embedding-3-small",
                    "sourceField": "body",
                },
            },
        },
    )

await client.createCollection({
  collectionName: "semantic-docs",
  indexConfigs: {
    body: {
      type: "text",
      analyzers: ["english"],
    },
    bodyEmbedding: {
      type: "vector",
      embedding: {
        provider: "openai",
        model: "text-embedding-3-small",
        sourceField: "body",
      },
    },
  },
});

curl -i -X POST "$BASE_URL/projects/$PROJECT_NAME/collections" \
  -H "content-type: application/json" \
  -H "x-api-key: $LAMBDADB_PROJECT_API_KEY" \
  -d '{
        "collectionName": "semantic-docs",
        "indexConfigs": {
          "body": {
            "type": "text",
            "analyzers": ["english"]
          },
          "bodyEmbedding": {
            "type": "vector",
            "embedding": {
              "provider": "openai",
              "model": "text-embedding-3-small",
              "sourceField": "body"
            }
          }
        }
      }'

For native embedding vector fields, do not send top-level dimensions or similarity in the field config. LambdaDB resolves and stores those values under embedding.

Create a partitioned collection

LambdaDB supports hash-based partitioning for a specified field. You choose the partition field and count through partitionConfig. At query time, supply partitionFilter with values of that field to search only the corresponding physical partitions; other partitions are not searched. Omitting partitionFilter leaves all partitions in the search scope. This is separate from LambdaDB’s internal sharding, which distributes execution and exposes no shard-count or placement setting to users.

from lambdadb import LambdaDB, models

with LambdaDB(project_api_key="YOUR_API_KEY", base_url="YOUR_BASE_URL", project_name="YOUR_PROJECT_NAME") as client:
    basic_config = {
        "url": {"type": "keyword"},
        "author": {"type": "keyword"},
        "content": {"type": "text", "analyzers": ["japanese", "korean", "english"]},
    }
    client.collections.create(
        collection_name="example-collection",
        index_configs=basic_config,
        partition_config={"field_name": "url", "data_type": "keyword", "num_partitions": 4},
    )

await client.createCollection({
  collectionName: "example-collection",
  indexConfigs: { url: { type: "keyword" }, author: { type: "keyword" }, content: { type: "text", analyzers: ["japanese", "korean", "english"] } },
  partitionConfig: { fieldName: "url", dataType: "keyword", numPartitions: 4 },
});

curl -i -X POST "$BASE_URL/projects/$PROJECT_NAME/collections" \
  -H "content-type: application/json" \
  -H "x-api-key: $LAMBDADB_PROJECT_API_KEY" \
  -d '{
        "collectionName": "example-collection",
        "indexConfigs": { "url": {"type": "keyword"}, "author": {"type": "keyword"}, "content": {"type": "text", "analyzers": ["japanese", "korean", "english"]} },
        "partitionConfig": { "fieldName": "url", "dataType": "keyword", "numPartitions": 4 }
      }'

Currently, only keyword type is supported for partitioning.

Snapshot retention

Every collection retains committed snapshots for 30 days by default. Set snapshotRetentionInDays to an integer from 1 through 31 when creating the collection, or change it later with the collection update API. Snapshots pinned by an existing tag remain available even after this retention period expires. Use tags to preserve specific committed versions as long-term savepoints. A tag protects its pinned snapshot, not the collection’s entire history. Collection metadata tags are labels and do not pin snapshots. Omitting retention on create selects the default; explicitly sending null is rejected. See Collection PATCH rules for update and metadata-tag semantics. Point-in-time history is available by creating a branch rather than cloning another collection. A source.asOf value is a Unix epoch timestamp in milliseconds and must refer to a branch in the same collection. See Branches, tags, and aliases.

Collection limits

Metric	Limit
Max number of collections	unlimited
Snapshot retention	1–31 days
Metadata tags	5 per collection

Get started

Migrations

Collections

Data versioning

Documents

Search

Manage Costs

Security

Parameters

Create a collection from scratch

Create a collection with native embeddings

Create a partitioned collection

Snapshot retention

Collection limits

​Parameters

​Create a collection from scratch

​Create a collection with native embeddings

​Create a partitioned collection

​Snapshot retention

​Collection limits

Parameters

Create a collection from scratch

Create a collection with native embeddings

Create a partitioned collection

Snapshot retention

Collection limits