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

# Manage collections

> List, describe, and delete LambdaDB collections using the Python, TypeScript, or Go SDKs and the REST API. Includes pagination and code examples.

This page shows you how to manage your existing collections including listing, describing, and deleting operations.

## List collections

Retrieve a complete list of all collections in your project along with their metadata and status information. The endpoint supports optional pagination.

| Parameter | Description                                      | Type    | Required | Default |
| :-------- | :----------------------------------------------- | :------ | :------- | :------ |
| size      | Max number of collections to return in one page. | integer |          |         |
| pageToken | Token for the next page of results.              | string  |          |         |

<CodeGroup>
  ```python Python theme={null}
  from lambdadb import LambdaDB

  with LambdaDB(project_api_key="YOUR_API_KEY", base_url="YOUR_BASE_URL", project_name="YOUR_PROJECT_NAME") as client:
      # First page (optional: size, page_token)
      res = client.collections.list(size=20)
      for c in res.collections:
          print(c.collection_name, c.num_docs)
      # Next page (if res.next_page_token is set)
      if res.next_page_token:
          res_next = client.collections.list(size=20, page_token=res.next_page_token)
  ```

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

  ```typescript TypeScript theme={null}
  import { LambdaDBClient } from "@functional-systems/lambdadb";

  const client = new LambdaDBClient({
    projectApiKey: "YOUR_API_KEY",
    baseUrl: "YOUR_BASE_URL",
    projectName: "YOUR_PROJECT_NAME",
  });
  // First page (optional: size, pageToken)
  const res = await client.listCollections({ size: 20 });
  console.log(res.collections);
  // Next page (if res.nextPageToken is set)
  if (res.nextPageToken) {
    const resNext = await client.listCollections({ size: 20, pageToken: res.nextPageToken });
  }
  ```

  ```go Go theme={null}
  client := lambdadb.New(
    lambdadb.WithBaseURL("YOUR_BASE_URL"),
    lambdadb.WithProjectName("YOUR_PROJECT_NAME"),
    lambdadb.WithAPIKey("YOUR_API_KEY"),
  )
  // First page (optional: Size, PageToken)
  opts := &lambdadb.ListCollectionsOpts{Size: lambdadb.Int64(20)}
  res, err := client.Collections.List(ctx, opts)
  if err != nil { log.Fatal(err) }
  for _, c := range res.Collections { _ = c }
  // Next page (if res.NextPageToken != nil)
  if res.NextPageToken != nil {
    resNext, _ := client.Collections.List(ctx, &lambdadb.ListCollectionsOpts{Size: lambdadb.Int64(20), PageToken: res.NextPageToken})
    _ = resNext
  }
  ```

  ```bash cURL theme={null}
  # $BASE_URL and $PROJECT_NAME match your LambdaDB Cloud project's region-specific base URL and project name.
  LAMBDADB_PROJECT_API_KEY="YOUR_API_KEY"

  # First page (optional: size, pageToken)
  curl -i -X GET "$BASE_URL/projects/$PROJECT_NAME/collections?size=20" \
    -H "x-api-key: $LAMBDADB_PROJECT_API_KEY"

  # Next page (use nextPageToken from previous response)
  curl -i -X GET "$BASE_URL/projects/$PROJECT_NAME/collections?size=20&pageToken=YOUR_PAGE_TOKEN" \
    -H "x-api-key: $LAMBDADB_PROJECT_API_KEY"
  ```
</CodeGroup>

The response includes detailed information about each collection. When there are more results, the response may include `nextPageToken` for fetching the next page:

```json theme={null}
{
  "collections": [
    {
      "projectName": "your-project",
      "collectionName": "example-collection",
      "indexConfigs": {
        "title": {"type": "text"},
        "category": {"type": "keyword"}
      },
      "numDocs": 1250,
      "sourceProjectName": "source-project-name",
      "sourceCollectionName": "source-collection-name",
      "sourceCollectionVersionId": "wR0NyDJbqDiHMaaV597GjczO2oGQyG7T",
      "collectionStatus": "ACTIVE"
    }
  ],
  "nextPageToken": "eyJ..."
}
```

## Describe a collection

Get detailed information about a specific collection, including its configuration, document count, and current status.

<CodeGroup>
  ```python Python theme={null}
  with LambdaDB(project_api_key="YOUR_API_KEY", base_url="YOUR_BASE_URL", project_name="YOUR_PROJECT_NAME") as client:
      meta = client.collection("example-collection").get()
      # or client.collections.get(collection_name="example-collection")
  ```

  ```typescript TypeScript theme={null}
  const meta = await client.collection("example-collection").get();
  console.log(meta);
  ```

  ```go Go theme={null}
  meta, err := client.Collection("example-collection").Get(ctx)
  if err != nil { log.Fatal(err) }
  ```

  ```bash cURL theme={null}
  curl -i -X GET "$BASE_URL/projects/$PROJECT_NAME/collections/example-collection" \
    -H "x-api-key: $LAMBDADB_PROJECT_API_KEY"
  ```
</CodeGroup>

The response provides comprehensive collection details:

```json theme={null}
{
  "projectName": "your-project",
  "collectionName": "example-collection",
  "indexConfigs": {
    "title": {
      "type": "text",
      "analyzers": ["standard", "korean"]
    },
    "embedding": {
      "type": "vector",
      "dimensions": 768,
      "similarity": "cosine"
    }
  },
  "numDocs": 1250,
  "sourceProjectName": "source-project-name",
  "sourceCollectionName": "source-collection-name",
  "sourceCollectionVersionId": "wR0NyDJbqDiHMaaV597GjczO2oGQyG7T",
  "collectionStatus": "ACTIVE"
}
```

## Delete a collection

Permanently delete a collection and all of its associated data and resources. This operation cannot be undone.

Deletion is **asynchronous**: the API returns **202 Accepted** and queues the work in the background. Until the job finishes, the collection name is still reserved—you may see `collectionStatus` **`DELETING`** from [Describe a collection](#describe-a-collection), and creating a collection with the same name can fail with a resource-already-exists error. For large collections (for example thousands of documents), this phase can take **a minute or longer**. Use the [wait-for-deletion pattern](#wait-for-deletion-before-recreating) before calling create again with the same name.

<CodeGroup>
  ```python Python theme={null}
  client.collections.delete(collection_name="collection-to-delete")
  ```

  ```typescript TypeScript theme={null}
  await client.collection("collection-to-delete").delete();
  ```

  ```go Go theme={null}
  err := client.Collection("collection-to-delete").Delete(ctx)
  if err != nil { log.Fatal(err) }
  ```

  ```bash cURL theme={null}
  curl -i -X DELETE "$BASE_URL/projects/$PROJECT_NAME/collections/collection-to-delete" \
    -H "x-api-key: $LAMBDADB_PROJECT_API_KEY"
  ```
</CodeGroup>

<Warning>
  Deleting a collection is irreversible and will permanently remove all documents and metadata. Make sure you have proper backups if needed before proceeding with this operation.
</Warning>

## Collection status

Collections can have the following status values:

| Status     | Description                                                                                 |
| :--------- | :------------------------------------------------------------------------------------------ |
| `CREATING` | Collection is being created and not yet available                                           |
| `ACTIVE`   | Collection is ready for read/write operations                                               |
| `DELETING` | Collection is being deleted asynchronously; the name stays reserved until removal completes |

## Wait for deletion before recreating

If you delete a collection and immediately call create with the **same** `collectionName`, the create request may fail (for example **Resource already exists** / `ResourceAlreadyExists`) even though you already issued delete. That is expected while the collection is still being removed.

**What to do:** After a successful delete call, poll **Describe** (`get`) until the collection **no longer exists** (typically HTTP **404** / `ResourceNotFound` from the API), then create. Checking `collectionStatus === "DELETING"` on each successful `get` confirms you are still in the teardown phase.

**Prefer `get` over `list` for this:** `list` can still include the collection for some time after delete; describe-by-name reflects the lifecycle more directly for a single collection.

<CodeGroup>
  ```python Python theme={null}
  import time

  collection_name = "knowledge-layer"
  poll_interval_s = 2.0
  max_wait_s = 900.0  # allow long-running deletes for large collections

  with LambdaDB(project_api_key="YOUR_API_KEY", base_url="YOUR_BASE_URL", project_name="YOUR_PROJECT_NAME") as client:
      client.collections.delete(collection_name=collection_name)

      deadline = time.monotonic() + max_wait_s
      while time.monotonic() < deadline:
          try:
              meta = client.collections.get(collection_name=collection_name)
          except Exception as exc:
              # When the collection is fully gone, describe returns 404 — use the not-found type your SDK maps to that response.
              code = getattr(exc, "status_code", None) or getattr(exc, "status", None)
              if code == 404:
                  break
              raise
          # Still present (often with status=DELETING); the name is not free yet.
          time.sleep(poll_interval_s)
      else:
          raise TimeoutError(f"Timed out after {max_wait_s}s waiting for {collection_name!r} to be removed")

      # Use the same index_configs you would pass to a normal create.
      client.collections.create(collection_name=collection_name, index_configs=your_index_configs)
  ```

  ```typescript TypeScript theme={null}
  import { LambdaDBClient } from "@functional-systems/lambdadb";

  const collectionName = "knowledge-layer";
  const pollMs = 2000;
  const timeoutMs = 900_000;

  const client = new LambdaDBClient({
    projectApiKey: "YOUR_API_KEY",
    baseUrl: "YOUR_BASE_URL",
    projectName: "YOUR_PROJECT_NAME",
  });

  await client.collection(collectionName).delete();

  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    try {
      // Still present (often with status=DELETING); the name is not free yet.
      await client.collection(collectionName).get();
      await new Promise((r) => setTimeout(r, pollMs));
    } catch (e: unknown) {
      // When the collection is fully removed, describe should fail with a not-found style error (often HTTP 404).
      const msg = e instanceof Error ? e.message : String(e);
      if (msg.toLowerCase().includes("not found") || msg.includes("404")) break;
      throw e;
    }
  }
  if (Date.now() >= deadline) throw new Error(`Timeout waiting for ${collectionName} to be removed`);

  await client.createCollection({
    collectionName,
    indexConfigs: {
      /* same fields as a normal create */
    },
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"errors"
  	"log"
  	"time"

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

  func example(ctx context.Context, client *lambdadb.Client) {
  	poll := 2 * time.Second
  	deadline := time.Now().Add(900 * time.Second)
  	name := "knowledge-layer"

  	if _, err := client.Collection(name).Delete(ctx); err != nil {
  		log.Fatal(err)
  	}

  	for time.Now().Before(deadline) {
  		meta, err := client.Collection(name).Get(ctx)
  		if err != nil {
  			var nf *apierrors.ResourceNotFoundError
  			if errors.As(err, &nf) {
  				break
  			}
  			log.Fatal(err)
  		}
  		_ = meta // still present (often with status=DELETING); the name is not free yet
  		time.Sleep(poll)
  	}
  	if time.Now().After(deadline) {
  		log.Fatalf("timeout waiting for collection %q to be removed", name)
  	}

  	_, err := client.Collections.Create(ctx, lambdadb.CreateCollectionOptions{
  		CollectionName: name,
  		IndexConfigs: map[string]interface{}{
  			/* same fields as a normal create */
  		},
  	})
  	if err != nil {
  		log.Fatal(err)
  	}
  }
  ```
</CodeGroup>