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.

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 managed embeddings

Managed embeddings let LambdaDB derive vector values from a source text field. Define the vector field with managedEmbedding: true and an embedding block. The source field must be a text field in the same collection. For the current provider and model matrix, see Managed 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",
                "managedEmbedding": True,
                "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",
      managedEmbedding: true,
      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",
            "managedEmbedding": true,
            "embedding": {
              "provider": "openai",
              "model": "text-embedding-3-small",
              "sourceField": "body"
            }
          }
        }
      }'

For managed 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.

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. 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

Parameters

Create a collection from scratch

Create a collection with managed embeddings

Create a partitioned collection

Snapshot retention

Collection limits

​Parameters

​Create a collection from scratch

​Create a collection with managed embeddings

​Create a partitioned collection

​Snapshot retention

​Collection limits

Parameters

Create a collection from scratch

Create a collection with managed embeddings

Create a partitioned collection

Snapshot retention

Collection limits