Skip to main content

Use Key-Value fields with the API

Key-value fields are a type of resource field that store structured data as a set of key-value pairs conforming to a predefined schema. Unlike free-form text fields, key-value fields are typed and validated, making them well-suited for structured metadata that needs to be filtered and searched programmatically, e.g: product attributes, document properties, or any structured facet you want to use to narrow search results.

Schemas​

Before writing key-value field data to a resource, you must define a schema that describes the expected shape of the data. Schemas are scoped to a Knowledge Box and managed through the /kb/{kbid}/kv-schemas endpoints.

A knowledge box can hold up to 20 schemas, each with up to 50 fields.

Schema structure​

A schema has:

  • id: Unique identifier within the knowledge box
  • description: Optional free-text description of what the schema represents. Used by LLM agents to understand the purpose of the field and its values
  • fields: List of field definitions, as follows

Field types​

Each field in a schema has a key, a type, and an optional description (also used by LLM agents). Fields are required by default and can be made optional by setting required: false.

Text (text)​

Stores a plain string value. Text fields can also be declared as repeated (see below).

{ "key": "color", "type": "text", "required": true }

Numeric: integer and float​

integer and float fields store numeric values. Both support range mode (see below).

{ "key": "quantity", "type": "integer", "required": false }
{ "key": "price",    "type": "float",   "required": true  }

Boolean (boolean)​

Stores true or false.

{ "key": "in_stock", "type": "boolean", "required": false }

Date (date)​

Stores a date-time value as an RFC 3339 string (time component and timezone offset required, e.g. "2024-01-15T00:00:00Z"). Date fields also support range mode (see below).

{ "key": "launched_at", "type": "date", "required": false }

Range fields​

integer, float, and date fields can be declared with "range": true. Instead of a single scalar value, a range field stores a closed interval with lower and upper bounds:

{ "key": "delivery_days", "type": "integer", "range": true, "required": false }

When writing data, provide the bounds as an object:

"delivery_days": { "lower": 1, "upper": 5 }

Range fields enable contains filters, checking whether a numeric value falls within the stored interval.

Repeated fields​

text fields can be declared with "repeated": true. Instead of a single string, a repeated field stores a list of strings:

{ "key": "labels", "type": "text", "repeated": true, "required": false }

When writing data, provide the values as a JSON array:

"labels": ["sale", "new-arrival"]

Repeated fields enable contains filters.

Example schema​

{
  "id": "product",
  "description": "A product in the clothing store catalog",
  "fields": [
    { "key": "color",         "type": "text",    "required": true  },
    { "key": "price",         "type": "float",   "required": true  },
    { "key": "in_stock",      "type": "boolean", "required": false },
    { "key": "stock",         "type": "integer", "required": false },
    { "key": "launched_at",   "type": "date",    "required": false },
    { "key": "delivery_days", "type": "integer", "range": true,    "required": false },
    { "key": "labels",        "type": "text",    "repeated": true, "required": false }
  ]
}

Managing fields​

Once a schema exists, key-value field data can be attached to resources.

Writing fields via the resource API​

Key-value fields can be included inline when creating or updating a resource. The key in the key_values map must match the id of the target schema:

POST /kb/{kbid}/resources
{
  "title": "White T-shirt",
  "key_values": {
    "product": {
      "data": {
        "color": "white",
        "price": 19.99,
        "in_stock": true,
        "stock": 140,
        "launched_at": "2024-06-01T00:00:00Z",
        "delivery_days": { "lower": 1, "upper": 3 },
        "labels": ["sale", "summer"]
      }
    }
  }
}

A key-value field on an existing resource can also be set or replaced directly:

PUT /kb/{kbid}/resource/{rid}/key_value/{field_id}

The data is validated against the schema at write time. Providing unknown keys, missing required keys, or values of the wrong type will return a 422 error.

Generating fields with Data Augmentation agents​

Key-value fields can also be populated automatically by Data Augmentation agents. A generator agent can extract structured information from other fields (such as text or files) and write it into a key-value field, following the schema you have defined. The schema description and individual field description values are used by agents to understand what information to extract and what each key means.

Querying​

Key-value fields can be used to filter resources in search and catalog queries via filter expressions. See the filter expressions reference for full syntax and examples.