Generic RAG channel configuration

The properties of a Generic RAG application define its pipeline: the document metadata, parsers, indexes, retriever, and answer generator. The backend calls this the channel configuration. This reference lists every property and component type. It is for platform engineers and application developers who set up Generic RAG applications, and is checked against backend 0.3.3.

How the configuration is used

Schema. The backend builds the schema from its components and serves it at /application-type-schema. DIAL Core validates application properties against it.
Server properties. Every property is a server property, so DIAL Core doesn't return it to clients.
Read on every request. The backend reads the properties from DIAL Core for each request, so a change applies to the next one.
No automatic reindex. Documents are indexed only on upload, on update, and on reindex. After a change to the parsers or indexes, reindex the documents.
Request options. Some options exist only in a request; see Per-request options.

Top-level properties

Property	Required	Default	Description
`metadata_schema`	No	A schema that allows any fields	The JSON Schema of document metadata. See Metadata schema.
`parsers`	No	`[]`	The parsers that extract chunks. With none, uploads of any type are accepted, but no chunks are extracted.
`indexes`	Yes	—	The indexes, at least one, by name
`retriever`	Yes	—	The retriever
`generation`	No	`{"type": "default"}`	The answer generator
`mcp`	No	Unset	Options of the MCP server

This is the upstream example application:

{
  "metadata_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "category": {"type": "string", "enable_filtering": true, "enable_in_mcp_retrieve_chunks": true},
      "published_on": {"type": "string", "format": "date", "enable_filtering": true, "enable_in_mcp_retrieve_chunks": true},
      "description": {"type": "string", "enable_in_mcp_retrieve_chunks": true},
      "tags": {"type": "array", "items": {"type": "string"}, "enable_filtering": true},
      "external_url": {"type": "string", "format": "uri"}
    },
    "additionalProperties": true
  },
  "parsers": [
    {"type": "unstructured_parser"},
    {"type": "page_extractor"}
  ],
  "indexes": {
    "keyword-elastic": {
      "type": "chunk",
      "display_name": "Keyword search",
      "indexer": {"type": "text_normalizer", "language": "english"},
      "storage": {"backend": "elastic"}
    },
    "generic-rag-embeddings": {
      "type": "chunk",
      "display_name": "Semantic search",
      "indexer": {"type": "text_embeddings", "deployment_name": "generic-rag-embeddings"}
    }
  },
  "retriever": {
    "type": "classic",
    "document_selector": {"type": "explicit"}
  },
  "generation": {
    "type": "default",
    "llm": {"deployment_name": "gpt-4.1-2025-04-14"}
  }
}

Metadata schema

metadata_schema is a JSON Schema, checked against its own meta-schema. The backend validates the metadata of every upload against it. Two keywords on a property tell the backend how to use the field:

Keyword	Effect
`enable_filtering: true`	The field can filter documents in requests, the channel API, and MCP tools. A string or date field can also sort documents.
`enable_in_mcp_retrieve_chunks: true`	The `retrieve_text_chunks` MCP tool returns the field with each chunk. When no field has it, the tool returns all metadata.

Filterable fields take these values in a filter:

Field type	Filter value	Matches
String, `"type": "string"`	A value or a list of values	Documents whose field equals one of them
String array, `"type": "array"` of strings	A value or a list of values	Documents whose array contains one of them
Date, `"type": "string"` with `"format": "date"`	`{"start": "<date>", "end": "<date>"}`, either one optional	Documents whose date is in the range, ends included

Once documents have values in a string or string array field, a filter on it accepts only those values.

Parsers

Each parser has a type, a transform list, and its own fields. A document goes through every parser that accepts its MIME type.

`type`	Accepts	Extracts	Fields
`unstructured_parser`	`application/pdf`, `text/markdown`, `text/plain`	Text chunks, split by title with the `unstructured` library's `fast` strategy, so no OCR	`chunk_size`, default `1000` characters. `combine_text_under_n_chars`, default `100`, which merges small chunks and must not exceed `chunk_size`.
`page_extractor`	`application/pdf`	One PNG image chunk per page	`image_size`, default `1536`: the size of a page image's longer side

The parsers' MIME types are the types a channel accepts for upload. A text chunk without a page number gets page 0.

Transforms

transform lists transforms that run in order on a parser's chunks. Release 0.3.3 has one.

page_description sends each page image chunk to a vision model. It saves the description items in the chunk's metadata, as a list of objects with text, kind, and element_index. kind is one of page_summary, page_key_fact, image_summary, image_key_fact, table_summary, and table_key_fact.

Field	Default	Description
`field`	`description`	The metadata field for the items
`llm`	`gpt-4.1-mini-2025-04-14`	The vision model, as an LLM configuration. Fields you set are merged with this default.
`max_image_size`	`800`	Larger page images are resized to fit this size before they're sent.
`max_concurrency`	`2`	Model calls at a time

To search the descriptions, add a chunk index with a text_embeddings indexer whose target is $.description[*].text.

Indexes

indexes maps index names to indexes. The name is internal. It identifies the index in requests, in reindexing, and in exports, and it's part of the index's storage name.

Field	Default	Description
`type`	`chunk`	`chunk` indexes chunks for answers. `document` indexes documents' fields for document search.
`display_name`	Required	The index's name in stages
`indexer`	Required	The indexer
`storage`	`{"backend": "pgvector"}`	The storage backend
`default_limit`	`7`	The most results a search of this index returns
`fields`	Required for `document`	JSON paths of the fields to index: `$.display_name`, `$.content` for `text/*` documents only, and `$.metadata.<field>` for string fields
`include_in_hybrid`	`true`, `document` only	Includes the index in a document search that names no indexes

Indexers

`type`	Index types	What it indexes	Fields
`text_embeddings`	`chunk`, `document`	Text, as vectors from an embeddings model	`deployment_name`, required. `max_retries`, default `3`.
`text_normalizer`	`chunk`, `document`	Text, as spaCy lemmas without stop words and punctuation	`language`: `english`, the default, or `ukrainian`
`text_noop`	`chunk`, `document`	Text as is	—
`image_embeddings`	`chunk`	Image chunks, as vectors from a multimodal embeddings model	`deployment_name`, required. `max_retries`, default `3`.
`page_description`	`chunk`	Deprecated. Page images, through a built-in `page_description` transform and a `text_embeddings` indexer.	`llm`, `embeddings` with `deployment_name` and `max_retries`, `max_image_size`, and `max_concurrency`

The three text indexers also take two fields, for chunk indexes:

Field	Default	Description
`target`	Unset	A JSON path in the chunk's metadata, such as `$.description[*].text`. When set, the indexer indexes the strings it finds instead of the chunk's text.
`concatenate_fields`	`false`	`true` joins the strings found by `target` into one record per chunk. Otherwise each string is a record of its own.

An image_embeddings indexer makes at most 10 model calls at a time in each backend process.

Storage backends

`backend`	Indexers	Search
`pgvector`, the default	All	A vector index is searched by cosine distance. A text index uses PostgreSQL full-text search, ranked by `ts_rank_cd`, in the language of `storage.text.language`, default `english`.
`elastic`	`text_normalizer` and `text_noop` only	An Elasticsearch `match` query on the indexed text. The Elasticsearch index is named `<prefix>-<channel key>-<index name>`.

storage.text.language accepts the text search configurations of the PostgreSQL database. The elastic backend exists only when the backend has ELASTICSEARCH_URL.

Retrievers

`type`	What it does
`simple`	Merges the results of the chunk indexes with reciprocal rank fusion
`classic`	Works like DIAL RAG. It replaces each page image found with the text chunks of that page, when the page has text. It adds up to `num_page_images_to_use` page images to the results.

Field	Retrievers	Default	Description
`title_field`	Both	Unset	A metadata field that holds the document title shown in citations. Without it, or when a document lacks the field, the document's name is shown.
`document_selector`	Both	`{"type": "all_documents"}`	The document selector
`num_page_images_to_use`	`classic`	`4`	The most page images passed to the model

Document selectors

`type`	Searches	Fields
`all_documents`, the default	All documents	—
`exact_documents`	The documents in `document_ids`	`document_ids`, set per request
`explicit`	The documents that match `filters` and `top_n`	`filters` and `top_n`, set per request. Without them, all documents.

filters is a list of metadata filters. A document matches when it meets all criteria of any one filter. top_n then keeps the first documents after sorting:

Field	Default	Description
`sort_by`	Required	Filterable string or date fields to sort by
`order`	`desc`	`asc` or `desc`
`limit`	`5`	The number of documents kept

Generators

`type`	What it does
`default`	Sends the query, the current date, and the results to an LLM, which answers and cites the results
`retrieval_only`	Returns every result as a citation, without an LLM call

The default generator has these fields:

Field	Default	Description
`llm`	`gpt-4.1-2025-04-14`	The LLM configuration
`system_prompt_template_override`	Unset	Replaces the built-in system prompt
`metadata_instructions`	`{}`	Metadata field names and instructions for the model. For each field in `metadata_schema`, the instruction joins the built-in prompt, and the field's value joins each result. Ignored when `system_prompt_template_override` is set.

LLM configuration

Field	Default	Description
`deployment_name`	`gpt-4.1-2025-04-14`	The model's deployment name in DIAL Core
`temperature`	`0.0`	From `0.0` to `2.0`
`max_retries`	`3`	Retries of a failed model call
`reasoning_effort`	Unset	`none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. What a model accepts depends on the model.

MCP options

Field	Description
`mcp.newest_sort`	Sort fields, as a list of `{"field": ..., "direction": "asc" \| "desc"}`, that order documents from newest to oldest. With it, `list_documents` sorts by recency and offers `newest_first`.
`mcp.filterable_fields`	The metadata fields MCP tools may filter by. Without it, all filterable fields.

Warning

Release 0.3.3 doesn't check these names against metadata_schema. An unknown or unsortable field in newest_sort fails every list_documents call. Unknown names in filterable_fields are dropped silently.

Per-request options

A chat completion request can override retriever and generation in custom_fields.configuration. The override is merged into the application's settings, so a request sets only what it changes. GET /v1/deployments/<application>/configuration returns the JSON schema of these options for an application.

These options exist only in a request:

Option	Where	Description
`retriever.top_k`	Both retrievers	The most results per chunk index, by index name. Each index defaults to its `default_limit`. `0` leaves an index out.
`retriever.document_selector.document_ids`	`exact_documents`	The IDs of the documents to search, at least one
`retriever.document_selector.filters`, `top_n`	`explicit`	See Document selectors.
`generation.current_date`	`default`	The date put in the prompt instead of today's, as `YYYY-MM-DD`. It makes an old question repeatable.

{
  "custom_fields": {
    "configuration": {
      "retriever": {
        "top_k": {"keyword-elastic": 0},
        "document_selector": {
          "type": "explicit",
          "filters": [{"category": "annual-report", "published_on": {"start": "2025-01-01"}}]
        }
      },
      "generation": {"current_date": "2025-12-31"}
    }
  },
  "messages": [{"role": "user", "content": "What changed in the risk outlook?"}]
}

The retrieval endpoint of the channel API takes the same retriever options. The MCP tools set the document selector from their arguments.

How the configuration is used​

Top-level properties​

Metadata schema​

Parsers​

Transforms​

Indexes​

Indexers​

Storage backends​

Retrievers​

Document selectors​

Generators​

LLM configuration​

MCP options​

Per-request options​

Further reading​