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

# Adding Data to Chroma Collections

> Learn how to add data to Chroma collections.

## Adding Data

Use `.add` to insert new records into a collection. Each record needs a unique string `id`.

<CodeGroup>
  ```python Python theme={null}
  collection.add(
      ids=["id1", "id2", "id3"],
      documents=["lorem ipsum...", "doc2", "doc3"],
      metadatas=[{"chapter": 3, "verse": 16}, {"chapter": 3, "verse": 5}, {"chapter": 29, "verse": 11}],
  )
  ```

  ```typescript TypeScript theme={null}
  await collection.add({
      ids: ["id1", "id2", "id3"],
      documents: ["lorem ipsum...", "doc2", "doc3"],
      metadatas: [{"chapter": 3, "verse": 16}, {"chapter": 3, "verse": 5}, {"chapter": 29, "verse": 11}],
  });
  ```

  ```rust Rust theme={null}
  // pub async fn add(
  //       &self,
  //       ids: Vec<String>,
  //       embeddings: Vec<Vec<f32>>,
  //       documents: Option<Vec<Option<String>>>,
  //       uris: Option<Vec<Option<String>>>,
  //       metadatas: Option<Vec<Option<Metadata>>>,
  //  ) -> Result<AddCollectionRecordsResponse, ChromaHttpClientError>
  collection.add(
      vec!["id1".to_string(), "id2".to_string(), "id3".to_string()],
      vec![
          vec![1.1, 2.3, 3.2],
          vec![4.5, 6.9, 4.4],
          vec![1.1, 2.3, 3.2],
      ],
      Some(vec![
          Some("lorem ipsum...".to_string()),
          Some("doc2".to_string()),
          Some("doc3".to_string()),
      ]),
      None,
      None,
  ).await?;
  ```
</CodeGroup>

You must provide either `documents`, `embeddings`, or both. `metadatas` are always optional.
When only providing `documents`, Chroma will generate embeddings for you using the collection's [embedding function](/docs/embeddings/embedding-functions).

If you've already computed embeddings, pass them alongside `documents`. Chroma will store both as-is without re-embedding the documents.

<CodeGroup>
  ```python Python theme={null}
  collection.add(
      ids=["id1", "id2", "id3"],
      embeddings=[[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2]],
      documents=["doc1", "doc2", "doc3"],
      metadatas=[{"chapter": 3, "verse": 16}, {"chapter": 3, "verse": 5}, {"chapter": 29, "verse": 11}],
  )
  ```

  ```typescript TypeScript theme={null}
  await collection.add({
      ids: ["id1", "id2", "id3"],
      embeddings: [[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2]],
      documents: ["doc1", "doc2", "doc3"],
      metadatas: [{"chapter": 3, "verse": 16}, {"chapter": 3, "verse": 5}, {"chapter": 29, "verse": 11}],
  })
  ```

  ```rust Rust theme={null}
  collection.add(
      vec!["id1".to_string(), "id2".to_string(), "id3".to_string()],
      vec![
          vec![1.1, 2.3, 3.2],
          vec![4.5, 6.9, 4.4],
          vec![1.1, 2.3, 3.2],
      ],
      Some(vec![
          Some("lorem ipsum...".to_string()),
          Some("doc2".to_string()),
          Some("doc3".to_string()),
      ]),
      None,
      None,
  ).await?;
  ```
</CodeGroup>

If your documents are stored elsewhere, you can add just embeddings and metadata. Use the `ids` to associate records with your external documents.
This is a useful pattern if your documents are very large, such as high-resolution
images or videos.

<CodeGroup>
  ```python Python theme={null}
  collection.add(
      ids=["id1", "id2", "id3"],
      embeddings=[[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2]],
      metadatas=[{"chapter": 3, "verse": 16}, {"chapter": 3, "verse": 5}, {"chapter": 29, "verse": 11}],
  )
  ```

  ```typescript TypeScript theme={null}
  await collection.add({
      ids: ["id1", "id2", "id3"],
      embeddings: [[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2]],
      metadatas: [{"chapter": 3, "verse": 16}, {"chapter": 3, "verse": 5}, {"chapter": 29, "verse": 11}],
  })
  ```

  ```rust Rust theme={null}
  collection.add(
      vec!["id1".to_string(), "id2".to_string(), "id3".to_string()],
      vec![
          vec![1.1, 2.3, 3.2],
          vec![4.5, 6.9, 4.4],
          vec![1.1, 2.3, 3.2],
      ],
      None,
      None,
      None,
  ).await?;
  ```
</CodeGroup>

## Metadata

Metadata values can be strings, integers, floats, or booleans. Additionally, you can store arrays of these types.

<CodeGroup>
  ```python Python theme={null}
  collection.add(
      ids=["id1"],
      documents=["lorem ipsum..."],
      metadatas=[{
          "chapter": 3,
          "tags": ["fiction", "adventure"],
          "scores": [1, 2, 3],
      }],
  )
  ```

  ```typescript TypeScript theme={null}
  await collection.add({
      ids: ["id1"],
      documents: ["lorem ipsum..."],
      metadatas: [{
          chapter: 3,
          tags: ["fiction", "adventure"],
          scores: [1, 2, 3],
      }],
  });
  ```

  ```rust Rust theme={null}
  use chroma::types::{Metadata, MetadataValue};

  let mut metadata = Metadata::new();
  metadata.insert("chapter".into(), MetadataValue::Int(3));
  metadata.insert(
      "tags".into(),
      MetadataValue::StringArray(vec!["fiction".to_string(), "adventure".to_string()]),
  );
  metadata.insert("scores".into(), MetadataValue::IntArray(vec![1, 2, 3]));
  ```
</CodeGroup>

All elements in an array must be the same type, and empty arrays are not allowed. You can filter on array metadata using the `$contains` and `$not_contains` operators — see [Metadata Filtering](/docs/querying-collections/metadata-filtering#using-array-metadata) for details.

## Behaviors

* If you add a record with an ID that already exists in the collection, it will be ignored without throwing an error. In order to overwrite data in your collection, you must [update](./update-data) the data.
* If the supplied embeddings don't match the dimensionality of embeddings already in the collection, an exception will be raised.