genkitx-astra-db
v0.2.0
Published
An Astra DB indexer and retriever for Genkit
Downloads
80
Maintainers
Readme
Astra DB Plugin for Genkit
This plugin provides a Astra DB retriever and indexer for Genkit.
Installation
npm i genkitx-astra-db
Prerequisites
You will need a DataStax account in which to run an Astra DB database. You can sign up for a free DataStax account here.
Once you have an account, create a Serverless Vector database. Once the database has been provisioned, create a collection. Ensure that you choose the same number of dimensions as the embedding provider you are going to use.
You will then need the database's API Endpoint, an Application Token and the name of the collection in order to configure the plugin.
Configuration
To use the Astra DB plugin, specify it when you call configureGenkit()
.
import { astraDB } from "genkitx-astra-db";
configureGenkit({
plugins: [
astraDB([
{
clientParams: {
applicationToken: "your_application_token",
apiEndpoint: "your_astra_db_endpoint",
namespace: "default_keyspace",
},
collectionName: "your_collection_name",
embedder: textEmbeddingGecko001,
},
]),
],
});
Client Parameters
You will need an Application Token and API Endpoint from Astra DB. You can either provide them through the clientParams
object or by setting the environment variables ASTRA_DB_APPLICATION_TOKEN
and ASTRA_DB_API_ENDPOINT
.
If you are using the default namespace, you do not need to pass it as config.
Options
collectionName
: You need to provide a collection name that matches a collection in the database accessed at the API endpointembedder
: You need to provide an embedder, like Google'stextEmbeddingGecko001
. Ensure that you have set up your collection with the correct number of dimensions for the embedder that you are usingembedderOptions
: If the embedder takes extra options you can provide them
Astra DB Vectorize
You do not need to provide an embedder
as you can use Astra DB Vectorize to generate your vectors. Ensure that you have set up your collection with an embedding provider. You can then skip the embedder
option:
import { astraDB } from "genkitx-astra-db";
configureGenkit({
plugins: [
astraDB([
{
clientParams: {
applicationToken: "your_application_token",
apiEndpoint: "your_astra_db_endpoint",
namespace: "default_keyspace",
},
collectionName: "your_collection_name",
},
]),
],
});
Usage
Import the indexer and retriever references like so:
import { astraDBIndexerRef, astraDBRetrieverRef } from "genkitx-astra-db";
Then get a reference using the collectionName
and an optional displayName
and pass the relevant references to the Genkit functions index()
or retrieve()
.
Indexer
export const astraDBIndexer = astraDBIndexerRef({
collectionName: "your_collection_name",
});
await index({
indexer: astraDBIndexer,
documents,
});
Retriever
export const astraDBRetriever = astraDBRetrieverRef({
collectionName: "your_collection_name",
});
await retrieve({
retriever: astraDBRetriever,
query,
});
Options
You can pass options to retrieve()
that will affect the retriever. The available options are:
k
: The number of documents to return from the retriever. The default is 5.filter
: AFilter
as defined by the Astra DB library. See below for how to use a filter
Advanced usage
If you want to perform a vector search with additional filtering (hybrid search) you can pass a schema type to astraDBRetrieverRef
. For example:
type Schema = {
_id: string;
text: string;
score: number;
};
export const astraDBRetriever = astraDBRetrieverRef<Schema>({
collectionName: "your_collection_name",
});
await retrieve({
retriever: astraDBRetriever,
query,
options: {
filter: {
score: { $gt: 75 },
},
},
});
You can find the operators that you can use in filters in the Astra DB documentation.
If you don't provide a schema type, you can still filter but you won't get type-checking on the filtering options.
Further information
For more on using indexers and retrievers with Genkit check out the documentation on Retrieval-Augmented Generation with Genkit.