SPB Git

Repository Public

metadata.md 4.8 KB 159 lines markdown

1<!-- source: https://docs.x.ai/developers/files/collections/metadata (from https://docs.x.ai/llms-full.txt, retrieved 2026-09-19T05:28:55Z) -->2#### Files & Collections34# Metadata Fields56Metadata fields allow you to attach structured attributes to documents in a collection. These fields enable:78* **Filtered retrieval** — Narrow search results to documents matching specific criteria (e.g., `author="Sandra Kim"`)9* **Contextual embeddings** — Inject metadata into chunks to improve retrieval accuracy (e.g., prepending document title to each chunk)10* **Data integrity constraints** — Enforce required fields or uniqueness across documents1112## Creating a Collection with Metadata Fields1314Define metadata fields using `field_definitions` when creating a collection:1516```bash17curl -X POST "https://management-api.x.ai/v1/collections" \18  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \19  -H "Content-Type: application/json" \20  -d '{21    "collection_name": "research_papers",22    "field_definitions": [23      { "key": "author", "required": true },24      { "key": "year", "required": true, "unique": true },25      { "key": "title", "inject_into_chunk": true }26    ]27  }'28```2930### Field Definition Options3132| Option | Description |33|--------|-------------|34| `required` | Document uploads must include this field. Defaults to `false`. |35| `unique` | Only one document in the collection can have a given value for this field. Defaults to `false`. |36| `inject_into_chunk` | Prepends this field's value to every embedding chunk, improving retrieval by providing context. Defaults to `false`. |3738## Uploading Documents with Metadata3940Include metadata as a JSON object in the `fields` parameter:4142```bash43curl -X POST "https://management-api.x.ai/v1/collections/{collection_id}/documents" \44  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \45  -F "name=paper.pdf" \46  -F "data=@paper.pdf" \47  -F "content_type=application/pdf" \48  -F 'fields={"author": "Sandra Kim", "year": "2024", "title": "Q3 Revenue Analysis"}'49```5051## Filtering Documents in Search5253Use the `filter` parameter to restrict search results based on metadata values. The filter uses AIP-160 syntax:5455```bash56curl -X POST "https://api.x.ai/v1/documents/search" \57  -H "Authorization: Bearer $XAI_API_KEY" \58  -H "Content-Type: application/json" \59  -d '{60    "query": "revenue growth",61    "source": { "collection_ids": ["collection_xxx"] },62    "filter": "author=\"Sandra Kim\" AND year>=2020"63  }'64```6566### Supported Filter Operators6768| Operator | Example | Description |69|----------|---------|-------------|70| `=` | `author="Jane"` | Equals |71| `!=` | `status!="draft"` | Not equals |72| `<`, `>`, `<=`, `>=` | `year>=2020` | Numeric/lexical comparison |73| `AND` | `a="x" AND b="y"` | Both conditions must match |74| `OR` | `a="x" OR a="y"` | Either condition matches |7576> [!NOTE]77>78> `AND` has higher precedence than `OR`, so `a="x" OR b="y" AND c="z"` is evaluated as `a="x" OR (b="y" AND c="z")`. Use parentheses to make grouping explicit.7980> [!WARNING]81>82> Wildcard matching (e.g., `author="E*"`) is not supported. All string comparisons are exact matches.8384> [!WARNING]85>86> Filtering on fields that don't exist in your documents returns no results. Double-check that field names match your collection's `field_definitions`.8788## AIP-160 Filter String Examples8990### Basic Examples9192```bash93# Equality (double or single quotes for strings with spaces)94author="Sandra Kim"95author='Sandra Kim'9697# Equality (no quotes needed for simple values)98year=202499status=active100101# Not equal102status!="archived"103status!='archived'104```105106### Comparison Operators107108```bash109# Numeric comparisons110year>=2020111year>2019112score<=0.95113price<100114115# Combined comparisons (range)116year>=2020 AND year<=2024117```118119### Logical Operators120121```bash122# AND - both conditions must match123author="Sandra Kim" AND year=2024124125# OR - either condition matches126status="pending" OR status="in_progress"127128# Combined (OR has higher precedence than AND)129department="Engineering" AND status="active" OR status="pending"130131# Use parentheses for clarity132department="Engineering" AND (status="active" OR status="pending")133```134135### Complex Examples136137```bash138# Multiple conditions139author="Sandra Kim" AND year>=2020 AND status!="draft"140141# Nested logic with parentheses142(author="Sandra Kim" OR author="John Doe") AND year>=2020143144# Multiple fields with mixed operators145category="finance" AND (year=2023 OR year=2024) AND status!="archived"146```147148## Quick Reference149150| Use Case | Filter String |151|----------|---------------|152| Exact match | `author="Sandra Kim"` |153| Numeric comparison | `year>=2020` |154| Not equal | `status!="archived"` |155| Multiple conditions | `author="Sandra Kim" AND year=2024` |156| Either condition | `status="pending" OR status="draft"` |157| Grouped logic | `(status="active" OR status="pending") AND year>=2020` |158| Complex filter | `category="finance" AND year>=2020 AND status!="archived"` |159
Files main
Menu

Theme