Metadatos y campos personalizados
En esta página
Contexto que el documento no incluye
Un informe técnico no siempre incluye en su cuerpo el nombre del autor, el año de redacción o su nivel de confidencialidad. Sin embargo, estos detalles marcan la diferencia entre una búsqueda que encuentra el documento correcto y otra que devuelve tres resultados irrelevantes. El sistema de metadatos de la colección sirve exactamente para esto: asociar información estructurada a cada documento para que la búsqueda pueda explotarla y tú puedas filtrar por ella.
Adjuntar campos a un documento
Al añadir un documento, el parámetro fields acepta pares clave-valor que defines libremente:
await client.collections.upload_document(
collection_id=collection_id,
name="technical-report-q1",
data=pdf_content,
fields={
"author": "Marie Dupont",
"year": "2026",
"department": "R&D",
"document_type": "report",
"confidentiality": "internal"
}
)
En este nivel no se impone ningún esquema: los nombres de los campos los eliges tú. Esta libertad resulta cómoda para el primer documento, pero se convierte en un problema al llegar al centésimo, cuando author, auteur y Author coexisten en la misma colección sin que funcione ningún filtro.
Establecer reglas a nivel de colección
Aquí es donde entran en juego las field_definitions, declaradas en la colección. Convierten un convenio oral en una restricción verificada por la API. Existen tres configuraciones:
| Configuración | Efecto |
|---|---|
required: true | Cada documento debe incluir este metadato |
unique: true | Dos documentos no pueden compartir el mismo valor |
inject_into_chunk: true | El metadato se añade al contenido indexado |
Una definición combina estas configuraciones campo por campo:
{
"field_definitions": [
{
"name": "author",
"required": true,
"inject_into_chunk": true
},
{
"name": "document_id",
"required": true,
"unique": true
},
{
"name": "year",
"required": false,
"inject_into_chunk": true
}
]
}
Lee este ejemplo como una política de documentos: todo documento tiene un autor y un ID; ese ID pertenece a un único documento, lo que bloquea duplicados durante la ingesta; y el año permanece opcional para evitar rechazar elementos sin fecha.
La opción que cambia la relevancia
De estas tres configuraciones, inject_into_chunk es la única que afecta a la calidad de la respuesta, y merece una mirada más detenida. Durante la indexación, un documento se divide en fragmentos (chunks) y, al activar esta opción, el valor del campo se copia en cada uno de ellos.
En la práctica, con author: "Marie Dupont" y inject_into_chunk: true, cada fragmento indexado lleva este nombre. Una pregunta como «¿Qué escribió Marie Dupont sobre la latencia de la red?» tiene entonces posibilidades de dar en el clavo, ya que el nombre aparece en el contenido buscado. Sin inyección, la misma pregunta depende únicamente del texto del informe, donde el autor podría aparecer solo en la portada.
Activa, pues, la inyección para campos que aportan contexto (autor, departamento, año, categoría) y déjala desactivada para campos administrativos como un ID interno, la fecha de carga o el estado de validación, que solo añadirían ruido.
Tres esquemas probados
Los metadatos útiles no se inventan en abstracto: surgen de las preguntas que se formulan a la base de datos. Una base de documentación técnica se organiza en torno al producto y la versión, ya que la primera pregunta de un usuario es casi siempre «¿qué versión?»:
{
"fields": {
"product": "Grok API",
"version": "v1",
"type": "reference",
"language": "en"
}
}
Una base de conocimientos de recursos humanos, en cambio, razona por categoría y fecha de entrada en vigor, ya que la respuesta incorrecta allí suele ser una política derogada:
{
"fields": {
"category": "hr-policy",
"effective_date": "2026-01-01",
"department": "all",
"status": "active"
}
}
Por último, una base jurídica se estructura en torno a las partes, el tipo de contrato y la expiración, lo que te permite recuperar acuerdos próximos a vencer en una única consulta:
{
"fields": {
"contract_type": "vendor",
"party": "Acme Corp",
"expiration": "2027-06-30",
"jurisdiction": "France"
}
}
Mantener un esquema coherente
La coherencia se pierde siempre por los mismos canales, y bastan unos pocos hábitos para mantenerla. Estandariza los formatos de los nombres de los campos: snake_case, en inglés, sin mezclar idiomas. Limita su cantidad: de cinco a diez campos cubren la mayoría de las necesidades; más allá de eso, los costes de mantenimiento superan las ganancias en relevancia. Gestiona inject_into_chunk con discernimiento, ya que cada campo inyectado aumenta el tamaño de los fragmentos y, por tanto, los costes de almacenamiento. Por último, documenta el esquema esperado para cada colección en un archivo accesible para el equipo: cuando varias personas lo alimentan, ese archivo, y no la memoria del creador, garantiza la coherencia.
Puntos clave
fieldsasocia metadatos de tipo clave-valor a cada documentofield_definitionsa nivel de colección definen reglas: required, unique, inject_into_chunk- La opción
inject_into_chunkmejora la relevancia de la búsqueda al añadir metadatos al contenido indexado - Estandariza tus esquemas de metadatos para mantener la coherencia de la colección