# Document Collections

{% hint style="warning" %}
**Deprecated:** The **Document Collections** feature is no longer available for new deployments. Existing deployments can continue to use this feature. To use RAG in new deployments, set up and connect an external vector database.
{% endhint %}

The IONOS AI Model Hub API allows you to access vector databases to persist your document collections and find semantically similar documents.

The vector database is used to persist documents in document collections. Each document is any form of pure text. In the document collection not only the input text is persisted, but also a transformation of the input text into an embedding. Each embedding is a vector of numbers. Input texts which are semantically similar have similar embeddings. A similarity search on a document collection finds the most similar embeddings for a given input text. These embeddings and the corresponding input text are returned to the user.

{% hint style="info" %}
**This is a vector store for RAG, not a traditional document database.**

For best results, store pre-chunked, focused passages rather than whole documents or files. Keep each entry focused on a single topic so the embedding accurately represents its meaning—improving the likelihood that semantic search returns the most relevant passage to the LLM.

The 65,535-byte (\~64 KB) per-entry limit is also your practical chunking boundary: if your source content is larger, split it into chunks before uploading.
{% endhint %}

## Overview

This guide is intended for developers. It assumes you have basic knowledge of:

* REST APIs and how to call them
* A programming language to handle REST API endpoints (for illustration purposes, the guide uses Python and Bash scripting)

By the end of this guide, you'll be able to:

* Create, delete and query a document collection in the IONOS vector database
* Save, delete and modify documents in the document collection and
* Answer customer queries using the document collection.

## Background

* The IONOS AI Model Hub API offers a vector database that you can use to persist text in document collections without having to manage corresponding hardware yourself.
* Our AI Model Hub API provides all required functionality without your data being transfered out of Germany.

## Before you begin

{% tabs %}
{% tab title="Python" %}
To get started, open your IDE to enter Python code.

Next generate a header document to authenticate yourself against the endpoints of our REST API:

```python
# Python example to specify header

IONOS_API_TOKEN = [YOUR API TOKEN HERE]
header = {
    "Authorization": f"Bearer {IONOS_API_TOKEN}", 
    "Content-Type": "application/json"
}
```

After this step, you have one variable **header** you can use to access our vector database.
{% endtab %}

{% tab title="Bash" %}
To get started, open a terminal and ensure that `curl` and `jq` is installed. While `curl` is essential for communicating with our API service, we use `jq` throughout our examples the improve the readability of our API results.
{% endtab %}
{% endtabs %}

Download the respective code files to easily access document collection-specific scripts and examples and generate the intended output:

{% tabs %}
{% tab title="Python Notebook" %}
Download this Python Notebook file to easily access document collection-specific scripts and examples and generate the intended output.

{% file src="/files/PAtLTa0gIXkEsNkd0Zeq" %}
{% endtab %}

{% tab title="Python Code" %}
Download this Python code file to easily access document collection-specific scripts and examples and generate the intended output.

{% file src="/files/RG5LPgvI55tR7ux8E3na" %}
{% endtab %}

{% tab title="Bash Code" %}
Download this Bash code file to easily access document collection-specific scripts and examples and generate the intended output.

{% file src="/files/0UxW3FUY94tb2O46zh4y" %}
{% endtab %}
{% endtabs %}

## Manage document collections

In this section, you learn how to create a document collection. We will use this document collection to fill it with the data from your knowledge base in the next step.

To track, if something is incorrect this section also shows how to:

* List existing document collections
* Remove document collections
* Get meta data of a document collection

### Create document collections

To create a document collection, you must specify the collection name and a description and invoke the endpoint to generate document collections:

{% tabs %}
{% tab title="Python" %}

```python
# Python example to specify header
import requests

COLLECTION_NAME = [ YOUR COLLECTION NAME HERE ]
COLLECTION_DESCRIPTION = [ YOUR COLLECTION DESCRIPTION HERE ]
CHUNK_OVERLAP = [ NUMBER OF OVERLAPPING TOKENS ]
CHUNK_SIZE = [ MAXIMUM NUMBER OF TOKENS PER DOCUMENT ]
EMBEDDING_MODEL = [ YOUR EMBEDDING MODEL HERE ]
DATA_BACKEND = [ THE BACKEND TO USE ]
endpoint = "https://inference.de-txl.ionos.com/collections"
body = {
    "properties": {
        "name": COLLECTION_NAME,
        "description": COLLECTION_DESCRIPTION,
        "chunking": {
            "enabled": True,
            "strategy": {
                "config": {
                    "chunk_overlap": CHUNK_OVERLAP, 
                    "chunk_size": CHUNK_SIZE
                }
            }
        },
        "embedding": {
            "model": EMBEDDING_MODEL
        },
        "engine": {
            "db_type": DATA_BACKEND
        }
    }
}
requests.post(endpoint, json=body, headers=header)
```

{% endtab %}

{% tab title="Bash" %}

```bash
#!/bin/bash

COLLECTION_NAME=[ YOUR COLLECTION NAME HERE ]
COLLECTION_DESCRIPTION=[ YOUR COLLECTION DESCRIPTION HERE ]
CHUNK_OVERLAP=[ NUMBER OF OVERLAPPING TOKENS ]
CHUNK_SIZE=[ MAXIMUM NUMBER OF TOKENS PER DOCUMENT ]
EMBEDDING_MODEL=[ YOUR EMBEDDING MODEL HERE ]
DATA_BACKEND=[ THE BACKEND TO USE ]
BODY='{ 
    "properties": { 
        "name": "'${COLLECTION_NAME}'", 
        "description": "'${COLLECTION_DESCRIPTION}'",
        "chunking": {
            "enabled": true,
            "strategy": {
                "config": {
                    "chunk_overlap": "'${CHUNK_OVERLAP}'",
                    "chunk_size": "'${CHUNK_SIZE}'"
                }
            }
        },
        "embedding": {
            "model": "'${EMBEDDING_MODEL}'"
        },
        "engine": {
            "db_type": "'${DATA_BACKEND}'"
        }
    } 
}'

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
        -H "Content-Type: application/json" \
        -d "$BODY" \
        https://inference.de-txl.ionos.com/collections
```

{% endtab %}
{% endtabs %}

You can specify the following parameters when you create your document collection:

**Chunking**

The AI Model Hub supports fixed-length chunking. Chunking is **recommended for all RAG use cases**, regardless of document size. Uploading whole documents—even small ones—produces diluted embedding vectors that reduce retrieval precision. Splitting content into smaller, focused chunks produces sharper embeddings and ensures the most relevant passage is returned to the LLM.

Benefits of chunking:

**Better retrieval precision:** Smaller, focused chunks produce sharper embeddings, resulting in a semantic search that returns the most relevant passage to the LLM.

* **Embedding model fit**: Embedding models have token limits; chunking ensures no content is silently truncated.
* **Semantic focus**: A chunk covering one topic is embedded more accurately than a document spanning many topics.

You can control chunking using:

* **CHUNK\_SIZE**: The maximum number of tokens per chunk. Recommended starting point: **256–512 tokens**.
* **CHUNK\_OVERLAP**: The number of overlapping tokens between consecutive chunks. Recommended starting point: **10–20% of CHUNK\_SIZE**. Example: 32–64 tokens for a chunk size of 256. Overlap preserves context across chunk boundaries.

Optimal values depend on your embedding model's context window and the nature of your source content.

**Embedding Model**

The AI Model Hub supports different embedding models. You can use any of them when saving your documents to the document collection by setting the parameter **EMBEDDING\_MODEL**. To find all available models, invoke the models endpoint and use the variable **id** as parameter for the **EMBEDDING\_MODEL**. For a more detailed documentation, see **Step 1** of [<mark style="color:blue;">Text Embedding</mark>](/cloud/ai/ai-model-hub/how-tos/text-embeddings.md).

**Database Engine**

The AI Model Hub supports different databases in the backend to persist your data. Upon creation of your collection, you can choose which of them to use by setting **DATA\_BACKEND** to:

* **pgvector**: PGVector uses a PostgreSQL database as the backend to persist the document collection. We offer the corresponding PostgreSQL as a Database as a Service (DBaaS) offering. This allows you to scale as your demands grow by switching from the managed PostgreSQL to your own DBaaS instance.
* **chromadb**: ChromaDB is a state-of-the-art database optimized for persisting document collections. It is strongly optimized but does not support relational database features like PostgreSQL.

If you remove the **chunking**, **embedding**, and **engine** sections from the body of your request, we will create a document collection with default parameters. Our approach does not apply chunking; sentence transformers will be used as the embedding models, and the data will be stored in our managed ChromaDB.

If the creation of the document collection was successful, the status code of the request is 201 and it returns a JSON document with all relevant information about the document collection.

To modify the document collection you need its identifier. You can extract it from the returned JSON document in the variable **id**.

### List Existing Document Collections

To ensure that the previous step went as expected, you can list the existing document collections.

To retrieve a list of all document collections saved by you:

{% tabs %}
{% tab title="Python" %}

```python
# Python example to list existing document collections
import requests

endpoint = "https://inference.de-txl.ionos.com/collections"
requests.get(endpoint, headers=header).json()
```

{% endtab %}

{% tab title="Bash" %}

```bash
#!/bin/bash

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
        -H "Content-Type: application/json" \
        https://inference.de-txl.ionos.com/collections
```

{% endtab %}
{% endtabs %}

This query returns a JSON document consisting of your document collections and corresponding meta information

The result consists of 8 attributes per collection of which 3 are relevant for you:

* **id**: The identifier of the document collection
* **properties.description**: The textual description of the document collection
* **properties.documentsCount**: The number of documents persisted in the document collection

If you have not created a collection yet, the field **items** is an empty list.

### Remove a Document Collection

If the list of document collections consists of document collections you do not need anymore, you can remove a document collection by invoking:

{% tabs %}
{% tab title="Python" %}

```python
# Python example to delete collections
import requests

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]
endpoint = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}"
requests.delete(endpoint, headers=header)
```

{% endtab %}

{% tab title="Bash" %}

```bash
#!/bin/bash
COLLECTION_ID=[ YOUR COLLECTION ID HERE ]
curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -X DELETE \
     -i https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}
```

{% endtab %}
{% endtabs %}

This query returns a status code which indicates whether the deletion was successful:

* 204: Status code for successfull deletion
* 404: Status code given the collection did not exist

### Get Meta Data for a Document Collection

If you are interested in the meta data of a collection, you can extract it by invoking:

{% tabs %}
{% tab title="Python" %}

```python
# Python example to extract meta information
import requests

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]
endpoint = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}"
result = requests.get(endpoint, headers=header)
result.status_code
```

{% endtab %}

{% tab title="Bash" %}

```bash
#!/bin/bash

COLLECTION_ID=[ YOUR COLLECTION ID HERE ]

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}
```

{% endtab %}
{% endtabs %}

This query returns a status code which indicates whether the collection exists:

* 200: Status code if the collection exists
* 404: Status code given the collection does not exist

The body of the request consists of all meta data of the document collection.

## Manage Documents in Document Collection

In this section, you learn how to add documents to the newly created document collection. To validate your insertion, this section also shows how to

* List the documents in the document collection,
* Get meta data for a document,
* Update an existing document and
* Prune a document collection.

### Add Documents to Document Collection

To add an entry to the document collection, you must at least specify the **content**, the **name** of the content, and the **contentType**:

{% tabs %}
{% tab title="Python" %}

```python
# Python example to add documents to a collection
import requests
import base64

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]
CONTENT = [ YOUR CONTENT HERE ]
NAME = [ YOUR NAME HERE]
content_base64 = base64.b64encode(CONTENT.encode('utf-8')).decode("utf-8")
body = { 
    "items": [{ 
        "properties": { 
            "name": NAME, 
            "contentType": "text/plain", 
            "content": content_base64
        }
    }]
}
endpoint = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}/documents"
requests.put(endpoint, json=body, headers=header)
```

{% endtab %}

{% tab title="Bash" %}

```bash
#!/bin/bash

COLLECTION_ID=[ YOUR COLLECTION ID HERE ]
CONTENT=[ YOUR CONTENT HERE ]
NAME=[ YOUR NAME HERE]

CONTENT_BASE64=$(echo -n ${CONTENT} | base64)
BODY='{
    "items": [{
        "properties": {
            "name": "'${NAME}'", 
            "contentType": "text/plain", 
            "content": "'${CONTENT_BASE64}'"
        }
    }]
}'

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -H "Content-Type: application/json" \
     -d "$BODY" \
     -X PUT \
     https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}/documents
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Note:**

You must encode your content using base64 before adding it to the document collection. Each document's **decoded content** must not exceed **65,535 bytes (\~64 KB)**. After base64 encoding, the value must not exceed \~87,380 characters. If your source content is larger, split it into chunks of ≤ 65,535 bytes before uploading.
{% endhint %}

This request returns a status code 200 if adding the document to the document collection was successful.

### List Existing Documents in Document Collection

To ensure that the previous step went as expected, you can list the existing documents of your document collection.

To retrieve a list of all documents in the document collection saved by you:

{% tabs %}
{% tab title="Python" %}

```python
# Python example to list all existing documents in a document collections
import requests

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]

endpoint_coll = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}"
endpoint = f"{endpoint_coll}/documents"

requests.get(endpoint, headers=header).json()
```

{% endtab %}

{% tab title="Bash" %}

```bash
#!/bin/bash

COLLECTION_ID=[ YOUR COLLECTION ID HERE ]

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -H "Content-Type: application/json" \
     https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}/documents
```

{% endtab %}
{% endtabs %}

This query returns a JSON document consisting of your documents in the document collection and corresponding meta information

The result has a field **items** with all documents in the collection. This field consists of 10 attributes per entry of which 5 are relevant for you:

* **id**: The identifier of the document
* **properties.content**: The base64 encoded content of the document
* **properties.name**: The name of the document
* **properties.description**: The description of the document
* **properties.labels.number\_of\_tokens**: The number of tokens in the document

If you have not created the collection yet, the request will return a status code 404. It will return a JSON document with the field **items** set to an empty list if no documents were added yet.

### Get Meta Data for a Document

If you are interested in the metadata of a document, you can extract it by invoking:

{% tabs %}
{% tab title="Python" %}

```python
# Python example to access meta data from a document
import requests

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]
DOCUMENT_ID = [ YOUR DOCUMENT ID HERE ]

endpoint_coll = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}"
endpoint = f"{endpoint_coll}/documents/{DOCUMENT_ID}"

requests.get(endpoint, headers=header).json()
```

{% endtab %}

{% tab title="Bash" %}

```bash
#!/bin/bash

COLLECTION_ID=[ YOUR COLLECTION ID HERE ]
DOCUMENT_ID=[ YOUR DOCUMENT ID HERE ]

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -H "Content-Type: application/json" \
     https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}/documents/${DOCUMENT_ID}
```

{% endtab %}
{% endtabs %}

This query returns a status code which indicates whether the document exists:

* 200: Status code if the document exists
* 404: Status code given the document does not exist

The body of the request consists of all meta data of the document.

### Update a Document

If you want to update a document, invoke:

{% tabs %}
{% tab title="Python" %}

```python
# Python example to update a document
import requests
import base64

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]
DOCUMENT_ID = [ YOUR DOCUMENT ID HERE ]
CONTENT = [ YOUR CONTENT HERE ]
NAME = [ YOUR NAME HERE ]

endpoint_coll = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}"
endpoint = f"{endpoint_coll}/documents/{DOCUMENT_ID}"
content_base64 = base64.b64encode(CONTENT.encode('utf-8')).decode("utf-8")
body = { 
    "properties": { 
        "id": DOCUMENT_ID, 
        "name": NAME, 
        "contentType": 
        "text/plain", 
        "content": content_base64
    }
}

requests.put(endpoint, json=body, headers=header)
```

{% endtab %}

{% tab title="Bash" %}

```bash
#!/bin/bash

COLLECTION_ID=[ YOUR COLLECTION ID HERE ]
DOCUMENT_ID=[ YOUR DOCUMENT ID HERE ]
CONTENT=[ YOUR CONTENT HERE ]
NAME=[ YOUR NAME HERE ]
CONTENT_BASE64=$(echo -n ${CONTENT} | base64)
BODY='{
    "properties": {
        "name": "'${NAME}'", 
        "id": "'${DOCUMENT_ID}'", 
        "contentType": "text/plain", 
        "content": "'${CONTENT_BASE64}'"
    }
}'
curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -H "Content-Type: application/json" \
     -d "$BODY" \
     -X PUT \
     https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}/documents/${DOCUMENT_ID}
```

{% endtab %}
{% endtabs %}

This will replace the existing entry in the document collection with the given **id** by the payload of this request.

### Prune a Document Collection

If you want to remove all documents from a document collection invoke:

{% tabs %}
{% tab title="Python" %}

```python
# Python example to prune a document collection
import requests

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]
endpoint_coll = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}"
endpoint = f"{endpoint_coll}/documents"
requests.delete(endpoint, headers=header)
```

{% endtab %}

{% tab title="Bash" %}

```bash
#!/bin/bash

COLLECTION_ID=[ YOUR COLLECTION ID HERE ]
curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -X DELETE \
     -i https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}/documents
```

{% endtab %}
{% endtabs %}

This query returns the status code 204 if pruning the document collection was successful.

## Query Documents in the Document Collection

Finally, this section shows how to use the document collection and the contained documents to answer a user query.

To retrieve the documents relevant for answering the user query, invoke the **query** endpoint as follows:

{% tabs %}
{% tab title="Python" %}

```python
# Python example to retrieve documents for answering a user query
import requests
import base64

COLLECTION_ID = [ YOUR COLLECTION ID HERE ]
USER_QUERY = [ USER QUERY HERE ]
NUM_OF_DOCUMENTS = [ NUMBER OF DOCUMENTS TO CONSIDER HERE ]

endpoint = f"https://inference.de-txl.ionos.com/collections/{COLLECTION_ID}/query"
body = {"query": USER_QUERY, "limit": NUM_OF_DOCUMENTS }

relevant_documents = requests.post(endpoint, json=body, headers=header)

[
    base64.b64decode(entry['document']['properties']['content']).decode()
    for entry in relevant_documents.json()['properties']['matches']
]
```

{% endtab %}

{% tab title="Bash" %}

```bash
#!/bin/bash

COLLECTION_ID=[ YOUR COLLECTION ID HERE ]
USER_QUERY=[ USER QUERY HERE ]
NUM_OF_DOCUMENTS=[ NUMBER OF DOCUMENTS TO CONSIDER HERE ]
BODY='{"query": "'${USER_QUERY}'", "limit": "'${NUM_OF_DOCUMENTS}'" }'

RESULT=$(curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -H "Content-Type: application/json" \
     -d "$BODY" \
     -X POST \
     https://inference.de-txl.ionos.com/collections/${COLLECTION_ID}/query)

echo "$RESULT" | \
jq -r '.["properties"]["matches"][].["document"]["properties"]["content"]' | \
base64 --decode 
```

{% endtab %}
{% endtabs %}

This will return a list of the **NUM\_OF\_DOCUMENTS** most relevant documents in your document collection for answering the user query.

## Summary

In this guide, you learned how to use the IONOS AI Model Hub API to conduct semantic similarity searches using our vector database.

Namely, you learned how to:

* Create a necessary document collection in the vector database and modify it
* Insert your documents into the document collection and modify the documents
* Conduct semantic similarity searches using your document collection.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/document-collections.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.