Retrievers API

API reference for retrievers and indexers in Genkit (JavaScript/TypeScript)

Retrievers find relevant documents based on queries, while indexers store documents for retrieval.

defineRetriever()

Defines and registers a retriever.

import { defineRetriever } from '@genkit-ai/ai';
import { z } from 'zod';

const myRetriever = defineRetriever(
  registry,
  {
    name: 'myRetriever',
    configSchema: z.object({
      k: z.number().default(10),
    }),
    info: {
      label: 'My Vector Store Retriever',
    },
  },
  async (query, options) => {
    // Retrieve relevant documents
    const docs = await vectorStore.search(query.text(), options.k);
    
    return {
      documents: docs,
    };
  }
);

Parameters

registry · Registry · required

The Genkit registry instance

options · object · required

name · string · required

Unique name for the retriever

configSchema · OptionsType

Zod schema for retriever-specific configuration

info · RetrieverInfo

Metadata about the retriever

Show RetrieverInfo properties

label · string

Human-readable label

supports · object

media · boolean

Whether the retriever supports media in queries

runner · RetrieverFn<OptionsType> · required

Implementation function

Function signature:

(query: Document, options: z.infer<OptionsType>) => Promise<RetrieverResponse>

Returns

retriever · RetrieverAction<OptionsType>

A retriever action that can be used with retrieve()

retrieve()

Retrieves documents based on a query.

import { retrieve } from '@genkit-ai/ai';

const documents = await retrieve(registry, {
  retriever: 'myRetriever',
  query: 'What is Genkit?',
  options: { k: 5 },
});

console.log(documents); // Array<Document>

Parameters

registry · Registry · required

The Genkit registry instance

params · RetrieverParams<CustomOptions> · required

retriever · RetrieverArgument<CustomOptions> · required

Retriever to use (string name, RetrieverAction, or RetrieverReference)

query · string | DocumentData · required

Query text or document

options · z.infer<CustomOptions>

Retriever-specific configuration

Returns

documents · Document[]

Array of retrieved documents

retrieverRef()

Creates a reference to a retriever.

import { retrieverRef } from '@genkit-ai/ai';

const myRetrieverRef = retrieverRef({
  name: 'myRetriever',
  info: {
    label: 'My Retriever',
  },
});

Parameters

options · RetrieverReference<CustomOptionsSchema> · required

name · string · required

Retriever name

configSchema · CustomOptionsSchema

Configuration schema

info · RetrieverInfo

Retriever metadata

Returns

reference · RetrieverReference<CustomOptionsSchema>

A retriever reference

defineIndexer()

Defines and registers an indexer for storing documents.

import { defineIndexer } from '@genkit-ai/ai';
import { z } from 'zod';

const myIndexer = defineIndexer(
  registry,
  {
    name: 'myIndexer',
    configSchema: z.object({
      collectionName: z.string(),
    }),
    embedderInfo: {
      dimensions: 768,
    },
  },
  async (documents, options) => {
    // Store documents in vector database
    await vectorStore.add(
      options.collectionName,
      documents
    );
  }
);

Parameters

registry · Registry · required

The Genkit registry instance

options · object · required

name · string · required

Unique name for the indexer

configSchema · IndexerOptions

Zod schema for indexer-specific configuration

embedderInfo · EmbedderInfo

Information about the embedder used by this indexer

runner · IndexerFn<IndexerOptions> · required

Implementation function

Function signature:

(documents: Document[], options: z.infer<IndexerOptions>) => Promise<void>

Returns

indexer · IndexerAction<IndexerOptions>

An indexer action that can be used with index()

index()

Indexes documents for retrieval.

import { index, Document } from '@genkit-ai/ai';

await index(registry, {
  indexer: 'myIndexer',
  documents: [
    Document.fromText('Document 1 content'),
    Document.fromText('Document 2 content'),
  ],
  options: { collectionName: 'my-collection' },
});

Parameters

registry · Registry · required

The Genkit registry instance

params · IndexerParams<CustomOptions> · required

indexer · IndexerArgument<CustomOptions> · required

Indexer to use (string name, IndexerAction, or IndexerReference)

documents · DocumentData[] · required

Documents to index

options · z.infer<CustomOptions>

Indexer-specific configuration

Returns

void · Promise<void>

Promise that resolves when indexing is complete

indexerRef()

Creates a reference to an indexer.

import { indexerRef } from '@genkit-ai/ai';

const myIndexerRef = indexerRef({
  name: 'myIndexer',
  info: {
    label: 'My Indexer',
  },
});

Parameters

options · IndexerReference<CustomOptionsSchema> · required

name · string · required

Indexer name

configSchema · CustomOptionsSchema

Configuration schema

info · IndexerInfo

Indexer metadata

Returns

reference · IndexerReference<CustomOptionsSchema>

An indexer reference

defineSimpleRetriever()

Defines a simple retriever that maps data into documents.

import { defineSimpleRetriever } from '@genkit-ai/ai';
import { z } from 'zod';

const menuRetriever = defineSimpleRetriever(
  registry,
  {
    name: 'menuRetriever',
    configSchema: z.object({
      category: z.string().optional(),
    }),
    content: 'description',
    metadata: ['id', 'name', 'price'],
  },
  async (query, config) => {
    // Query database and return items
    return await db.searchMenu(query.text(), config);
  }
);

Parameters

registry · Registry · required

The Genkit registry instance

options · SimpleRetrieverOptions<C, R> · required

name · string · required

Retriever name

configSchema · C

Configuration schema

content · string | ((item: R) => Document['content'] | string)

How to extract content from returned items

metadata · string[] | ((item: R) => Document['metadata'])

How to extract metadata from returned items

handler · (query: Document, config: z.infer<C>) => Promise<R[]> · required

Function that queries the datastore

Returns

retriever · RetrieverAction

A retriever action

Types

RetrieverResponse

interface RetrieverResponse {
  documents: DocumentData[];
}

RetrieverAction

type RetrieverAction<CustomOptions extends z.ZodTypeAny = z.ZodTypeAny> =
  Action<typeof RetrieverRequestSchema, typeof RetrieverResponseSchema> & {
    __configSchema?: CustomOptions;
  };

IndexerAction

type IndexerAction<IndexerOptions extends z.ZodTypeAny = z.ZodTypeAny> =
  Action<typeof IndexerRequestSchema, z.ZodVoid> & {
    __configSchema?: IndexerOptions;
  };

CommonRetrieverOptionsSchema

const CommonRetrieverOptionsSchema = z.object({
  k: z.number().describe('Number of documents to retrieve').optional(),
});

Example: Complete RAG Setup

import { ai } from './genkit';
import { Document } from '@genkit-ai/ai';
import { z } from 'zod';

// Define indexer
const myIndexer = ai.defineIndexer(
  {
    name: 'myVectorStore',
    configSchema: z.object({
      collection: z.string(),
    }),
  },
  async (documents, options) => {
    const embeddings = await embedDocuments(documents);
    await vectorDb.insert(options.collection, documents, embeddings);
  }
);

// Define retriever
const myRetriever = ai.defineRetriever(
  {
    name: 'myVectorStore',
    configSchema: z.object({
      k: z.number().default(5),
    }),
  },
  async (query, options) => {
    const queryEmbedding = await embedText(query.text());
    const results = await vectorDb.search(queryEmbedding, options.k);
    
    return {
      documents: results.map(r => r.document),
    };
  }
);

// Index documents
await ai.index({
  indexer: myIndexer,
  documents: [
    Document.fromText('Genkit is a framework for AI apps'),
    Document.fromText('Firebase is a backend platform'),
  ],
  options: { collection: 'docs' },
});

// Retrieve and generate
const docs = await ai.retrieve({
  retriever: myRetriever,
  query: 'What is Genkit?',
  options: { k: 3 },
});

const response = await ai.generate({
  model: gemini15Flash,
  prompt: 'Answer based on context',
  docs,
});