> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unstructured.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Astra DB
First time creating a connector? [Read this first](/api-reference/workflow/connector-first-time-reqs).
Send processed data from Unstructured to Astra DB.
## Requirements
You will need:
* An IBM Cloud account or DataStax account.
* For an IBM Cloud account, [sign up](https://cloud.ibm.com/registration) for an IBMid, and then [sign in](https://accounts.datastax.com/session-service/v1/login) to DataStax with your IBMid.
* For a DataStax account, [sign up](https://astra.datastax.com/signup) for a DataStax account, and then [sign in](https://accounts.datastax.com/session-service/v1/login) to DataStax with your DataStax account.
* An Astra DB database in the DataStax account. To create a database:
a. After you sign in to DataStax, click **Create database**.
b. Click the **Serverless (vector)** tile, if it is not already selected.
c. For **Database name**, enter some unique name for the database.
d. Select a **Provider** and a **Region**, and then click **Create database**.
[Learn more](https://docs.datastax.com/en/astra-db-classic/databases/manage-create.html).
* An application token for the database. To create an application token:
a. After you sign in to DataStax, in the list of databases, click the name of the target database.
b. On the **Overview** tab, under **Database Details**, in the **Application Tokens** tile, click **Generate Token**.
c. Enter some **Token description** and select and **Expiration** time period, and then click **Generate token**.
d. Save the application token that is displayed to a secure location, and then click **Close**.
[Learn more](https://docs.datastax.com/en/astra-db-serverless/administration/manage-application-tokens.html).
* A keyspace in the database. To create a keyspace:
a. After you sign in to DataStax, in the list of databases, click the name of the target database.
b. On the **Data Explorer** tab, in the **Keyspace** list, select **Create keyspace**.
c. Enter some **Keyspace name**, and then click **Add keyspace**.
[Learn more](https://docs.datastax.com/en/astra-db-serverless/databases/manage-keyspaces.html#keyspaces).
* A collection in the keyspace.
For the [Unstructured Pipelines](/pipelines/overview) and [Unstructured API](/api-reference/overview):
* An existing collection is not required. At runtime, the collection behavior is as follows:
* If an existing collection name is specified, and Unstructured generates embeddings,
but the number of dimensions that are generated does not match the existing collection's embedding settings, the run will fail.
You must change your Unstructured embedding settings or your existing collection's embedding settings to match, and try the run again.
* If a collection name is not specified, Unstructured creates a new collection in your keyspace. If Unstructured generates embeddings,
the new collection's name will be `u__`.
If Unstructured does not generate embeddings, the new collection's name will be `u
b. On the **Data Explorer** tab, in the **Keyspace** list, select the name of the target keyspace.
c. In the **Collections** list, select **Create collection**.
d. Enter some **Collection name**.
e. Turn on **Vector-enabled collection**, if it is not already turned on.
f. Choose a mode for **Embedding generation method**. See [Astra DB generated embeddings](#astra-db-generated-embeddings).
g. If you chose **Bring my own**, enter the number of dimensions for the embedding model that you plan to use.
h. For **Similarity metric**, select **Cosine**.
i. Click **Create collection**.
[Learn more](https://docs.datastax.com/en/astra-db-serverless/databases/manage-collections.html#create-collection).
## Examples
To create an Astra DB destination connector, see the following examples.
For more information on working with destination connectors using the Unstructured API, see [Destination endpoints](/api-reference/api/destination/destination-apis).
```python Python SDK theme={null}
import os
from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import CreateDestinationRequest
from unstructured_client.models.shared import CreateDestinationConnector
with UnstructuredClient(api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")) as client:
response = client.destinations.create_destination(
request=CreateDestinationRequest(
create_destination_connector=CreateDestinationConnector(
name="",
type="astradb",
config={
"token": "",
"api_endpoint": "",
"collection_name": "",
"keyspace": "",
"batch_size": ,
"flatten_metadata": ,
"binary_encode_vectors": ,
"enable_lexical_search": ,
"astra_generated_embeddings":
}
)
)
)
print(response.destination_connector_information)
```
```bash curl theme={null}
curl --request 'POST' --location \
"$UNSTRUCTURED_API_URL/destinations" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
--header 'content-type: application/json' \
--data \
'{
"name": "",
"type": "astradb",
"config": {
"token": "",
"api_endpoint": "",
"collection_name": "",
"keyspace": "",
"batch_size": ,
"flatten_metadata": "",
"binary_encode_vectors": "",
"enable_lexical_search": "",
"astra_generated_embeddings": ""
}
}'
```
## Configuration settings
Replace the preceding placeholders as follows:
A unique name for this connector.
The application token for the database.
The database's associated API endpoint.
The name of the collection in the keyspace. If no value is provided, see the beginning of this article for the behavior at run time.
The name of the keyspace in the collection.
The maximum number of records to send per batch.
Set to `true` to flatten the metadata into each record. Specifically, when flattened, the metadata key values are brought to the top level of the element, and the `metadata` key itself is removed.
Set to `false` to upload vectors as a list of numbers. This is more efficient, but it makes it harder to view and work with vectors in the UI.
Set to `true` to enable lexical and hybrid search. See [Lexical search](#lexical-search).
Set to `true` to use an Astra vectorize integration for embeddings. See [Astra DB generated embeddings](#astra-db-generated-embeddings).
## Lexical search
When **Enable Lexical Search** is enabled, document text will be inserted into the `$lexical` field for lexical and hybrid search capabilities.
Your collection must be configured for lexical search, and your database must be in one of the supported AWS regions. For more information, see [Find data with lexicographical matching](https://docs.datastax.com/en/astra-db-serverless/databases/lexical-search.html) in the Astra DB documentation. Otherwise, you will encounter the following error when running a job:
` The Collection . does not have Lexical feature enabled. (LEXICAL_NOT_ENABLED_FOR_COLLECTION) [with 0 inserted ids])`
## Astra DB generated embeddings
When **Astra DB Generated Embeddings** is enabled:
* Your document text will be inserted into the `$vectorize` field.
* Astra DB will automatically populate the `$vector` field with embeddings.
* Your workflow **must not** include an embedder node.
* You **must** have an embedding provider configured for your collection.
When **Astra DB Generated Embeddings** is disabled (the default):
* Unstructured will insert embeddings directly into the `$vector` field
* Your workflow **must** include an embedder node.
For more information, see [Auto-generate embeddings with vectorize](https://docs.datastax.com/en/astra-db-serverless/databases/embedding-generation.html) in the Astra DB documentation.
### Troubleshooting
You might encounter the following errors when running a job that uses this connector:
**Error**:
`Unable to vectorize data, embedding service not configured for the collection : (EMBEDDING_SERVICE_NOT_CONFIGURED) [with 0 inserted ids])`
You've enabled **Astra DB Generated Embeddings**, but your collection does not have an embedding provider. Either disable **Astra DB Generated Embeddings** in your connector settings, or recreate your collection with an embedding provider.
**Error**:
`Cannot use Unstructured embeddings and Astra-generated embeddings simultaneously. Please disable Astra generated embeddings or remove the Unstructured embedder.`
**or**:
`No vectors provided. Please enable an Unstructured embedding provider or configure Astra to generate embeddings.`
You must choose either Unstructured or Astra DB embeddings. Configuring neither, or both, is unsupported.