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

# Collections Guide

> Organize memories into logical collections

A collection is a named container that groups related memories together. You create collections, assign memories to them, and scope searches to them.

## Why Use Collections?

* **Separate contexts**: Keep work, personal, and project memories distinct
* **Targeted search**: Search only within relevant collections
* **Access control**: Different API keys can have different collection permissions
* **Multi-tenancy**: Isolate data for different users or customers

## Creating Collections

<Note>Collection names are case-insensitive. "Work" and "work" are treated as duplicates.</Note>

<CodeGroup>
  ```python Python theme={null}
  from nebula import Nebula
  nebula = Nebula()

  collection = nebula.collections.create(
      name="Research Papers",
      description="Academic research documents",
  ).results
  ```

  ```javascript JavaScript theme={null}
  import Nebula from '@nebula-ai/sdk';
  const client = new Nebula({ apiKey: process.env.NEBULA_API_KEY });

  const { results: collection } = await client.collections.create({
    name: 'Research Papers',
    description: 'Academic research documents',
  });
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.zeroset.com/v1/collections" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{"name": "Research Papers", "description": "Academic research documents"}'
  ```
</CodeGroup>

For hosted SaaS workspaces that need graph data stored in customer-owned object storage, create the collection with a workspace storage target. See [Customer-Owned Object Storage](/guides/customer-owned-storage).

## Storing Memories in Collections

Always specify `collection_id` when storing memories:

<CodeGroup>
  ```python Python theme={null}
  nebula.memories.create(
      collection_id=collection.id,
      raw_text="Q4 planning meeting notes",
      metadata={"type": "meeting"},
  )
  ```

  ```javascript JavaScript theme={null}
  await client.memories.create({
    collection_id: collection.id,
    raw_text: 'Q4 planning meeting notes',
    metadata: { type: 'meeting' },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.zeroset.com/v1/memories" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
      "collection_id": "COLLECTION_ID",
      "kind": "document",
      "raw_text": "Q4 planning meeting notes",
      "metadata": {"type": "meeting"}
    }'
  ```
</CodeGroup>

## Searching Within Collections

<CodeGroup>
  ```python Python theme={null}
  # Search specific collection
  results = nebula.memories.search(query="deadlines", collection_ids=["Work"]).results

  # Search multiple collections
  results = nebula.memories.search(query="notes", collection_ids=["Work", "Personal"]).results

  # Search all accessible collections
  results = nebula.memories.search(query="important").results
  ```

  ```javascript JavaScript theme={null}
  // Search specific collection
  const { results } = await client.memories.search({
    query: 'deadlines',
    collection_ids: ['Work'],
  });

  // Search multiple collections
  const { results: results2 } = await client.memories.search({
    query: 'notes',
    collection_ids: ['Work', 'Personal'],
  });

  // Search all accessible collections
  const { results: results3 } = await client.memories.search({ query: 'important' });
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.zeroset.com/v1/memories/search" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{"query": "deadlines", "collection_ids": ["Work"]}'
  ```
</CodeGroup>

<Tip>Search accepts collection names or UUIDs. When storing memories, `collection_id` must be a UUID.</Tip>

## Managing Collections

<Tabs>
  <Tab title="List">
    <CodeGroup>
      ```python Python theme={null}
      collections = nebula.collections.list(limit=50).results
      work_collections = nebula.collections.list(name="Work").results
      ```

      ```javascript JavaScript theme={null}
      const { results: collections } = await client.collections.list({ limit: 50 });
      const { results: workCollections } = await client.collections.list({ name: 'Work' });
      ```

      ```bash cURL theme={null}
      curl -X GET "https://api.zeroset.com/v1/collections?limit=50" \
        -H "Authorization: Bearer YOUR_API_KEY"
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Get">
    <CodeGroup>
      ```python Python theme={null}
      collection = nebula.collections.retrieve(collection_id).results
      ```

      ```javascript JavaScript theme={null}
      const { results: collection } = await client.collections.retrieve(collectionId);
      ```

      ```bash cURL theme={null}
      curl -X GET "https://api.zeroset.com/v1/collections/YOUR_COLLECTION_ID" \
        -H "Authorization: Bearer YOUR_API_KEY"
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Update">
    <CodeGroup>
      ```python Python theme={null}
      nebula.collections.update(
          collection.id,
          name="Updated Name",
          description="New description",
      )
      ```

      ```javascript JavaScript theme={null}
      await client.collections.update(collection.id, {
        name: 'Updated Name',
        description: 'New description',
      });
      ```

      ```bash cURL theme={null}
      curl -X POST "https://api.zeroset.com/v1/collections/YOUR_COLLECTION_ID" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer YOUR_API_KEY" \
        -d '{"name": "Updated Name", "description": "New description"}'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Delete">
    <CodeGroup>
      ```python Python theme={null}
      nebula.collections.delete(collection_id)
      ```

      ```javascript JavaScript theme={null}
      await client.collections.delete(collectionId);
      ```

      ```bash cURL theme={null}
      curl -X DELETE "https://api.zeroset.com/v1/collections/YOUR_COLLECTION_ID" \
        -H "Authorization: Bearer YOUR_API_KEY"
      ```
    </CodeGroup>

    <Warning>Deleting a collection removes its graph data and vector sources. The underlying memory records are disassociated from the collection, not deleted.</Warning>
  </Tab>
</Tabs>

## Patterns and Tips

| Pattern                          | When to Use                                  |
| -------------------------------- | -------------------------------------------- |
| **One collection per user**      | User-specific memory/context                 |
| **One collection per project**   | Project-scoped documentation                 |
| **One collection per data type** | Different content types (docs, chats, notes) |