Metadonnees et champs personnalises

Enrichir vos documents avec des metadonnees

Les collections ne se limitent pas a stocker des fichiers. Le systeme de metadonnees vous permet d’associer des informations structurees a chaque document : auteur, date, categorie, version. Ces metadonnees ameliorent la precision des recherches et permettent le filtrage.

Champs personnalises (fields)

Lors de l’ajout d’un document a une collection, vous pouvez definir des champs personnalises via le parametre fields :

await client.collections.upload_document(
    collection_id=collection_id,
    name="rapport-technique-q1",
    data=pdf_content,
    fields={
        "author": "Marie Dupont",
        "year": "2026",
        "department": "R&D",
        "document_type": "rapport",
        "confidentiality": "interne"
    }
)

Ces champs sont des paires cle-valeur libres. Vous definissez vos propres noms de champs selon les besoins de votre organisation.

Definitions de champs (field_definitions)

Au niveau de la collection, vous pouvez definir des field_definitions pour structurer les metadonnees attendues. Cela permet de :

• Rendre un champ obligatoire (required: true) : chaque document doit avoir cette metadonnee
• Imposer l’unicite (unique: true) : deux documents ne peuvent pas avoir la meme valeur pour ce champ
• Injecter dans les chunks (inject_into_chunk: true) : la metadonnee est ajoutee au contenu indexe pour ameliorer la pertinence des recherches

Exemple de definitions

{
  "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
    }
  ]
}

L’option inject_into_chunk

Cette option merite une attention particuliere. Quand inject_into_chunk est active, la valeur du champ est ajoutee a chaque fragment (chunk) du document lors de l’indexation.

Concretement, si un document a le champ author: "Marie Dupont" avec inject_into_chunk: true, chaque chunk indexe contiendra cette information. Resultat : une recherche portant sur les documents de Marie Dupont sera plus pertinente car le nom apparait dans le contenu indexe.

Quand activer inject_into_chunk

• Activez-le pour les champs qui apportent du contexte de recherche : auteur, departement, annee, categorie
• Desactivez-le pour les champs purement administratifs : identifiant interne, date d’upload, statut de validation

Cas d’usage concrets

Base documentaire technique

{
  "fields": {
    "product": "Grok API",
    "version": "v3",
    "type": "reference",
    "language": "fr"
  }
}

Base de connaissances RH

{
  "fields": {
    "category": "politique-rh",
    "effective_date": "2026-01-01",
    "department": "all",
    "status": "active"
  }
}

Base juridique

{
  "fields": {
    "contract_type": "fournisseur",
    "party": "Acme Corp",
    "expiration": "2027-06-30",
    "jurisdiction": "france"
  }
}

Bonnes pratiques

• Standardisez vos noms de champs : utilisez des conventions coherentes (snake_case, anglais ou francais, mais pas un melange)
• Limitez le nombre de champs : 5 a 10 champs suffisent pour la plupart des cas. Trop de champs complexifient la gestion sans apporter de valeur
• Utilisez inject_into_chunk avec discernement : chaque champ injecte augmente la taille des chunks et donc le cout de stockage
• Documentez vos schemas : notez quelque part les champs attendus pour chaque collection, surtout si plusieurs personnes y contribuent

Points cles a retenir

• Les fields associent des metadonnees cle-valeur a chaque document
• Les field_definitions au niveau collection definissent les regles : required, unique, inject_into_chunk
• L’option inject_into_chunk ameliore la pertinence des recherches en ajoutant la metadonnee au contenu indexe
• Standardisez vos schemas de metadonnees pour maintenir la coherence de vos collections