Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Metagegevens en aangepaste velden

Les 7 van 16 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Context die het document niet bevat
  2. Velden aan een document koppelen
  3. Regels op collectieniveau instellen
  4. De optie die relevantie verandert
  5. Drie bewezen schema’s
  6. Een consistent schema behouden
  7. Belangrijkste punten

Context die het document niet bevat

Een technisch rapport bevat niet altijd de naam van de auteur, het jaar van opstellen of het vertrouwelijkheidsniveau in de lopende tekst. Toch maken deze details het verschil tussen een zoekopdracht die het juiste document vindt en een die drie irrelevante resultaten retourneert. Het metagegevenssysteem voor collecties dient precies dit doel: het koppelen van gestructureerde informatie aan elk document, zodat de zoekfunctie deze kan benutten en u erop kunt filteren.

Velden aan een document koppelen

Bij het toevoegen van een document accepteert de parameter fields sleutel-waardeparen die u vrij kunt definiëren:

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"
    }
)

Op dit niveau wordt geen schema afgedwongen: u kiest zelf de veldnamen. Deze vrijheid voelt comfortabel bij het eerste document, maar wordt bij het honderdste een probleem wanneer author, auteur en Author naast elkaar bestaan in dezelfde collectie zonder dat filters werken.

Regels op collectieniveau instellen

Hier komen field_definitions om de hoek kijken, gedeclareerd op de collectie. Ze zetten een mondelinge afspraak om in een door de API gecontroleerde beperking. Er zijn drie instellingen mogelijk:

InstellingEffect
required: trueElk document moet deze metagegevens bevatten
unique: trueTwee documenten kunnen niet dezelfde waarde delen
inject_into_chunk: trueDe metagegevens worden toegevoegd aan de geïndexeerde inhoud

Een definitie combineert deze instellingen per veld:

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

Lees dit voorbeeld als een documentbeleid: elk document heeft een auteur en een ID, die ID behoort toe aan slechts één document—wat duplicaten bij ingestie blokkeert—en het jaar blijft optioneel om te voorkomen dat items zonder datum worden geweigerd.

De optie die relevantie verandert

Van deze drie instellingen is inject_into_chunk de enige die de kwaliteit van het antwoord beïnvloedt, en deze verdient een nadere blik. Tijdens het indexeren wordt een document opgesplitst in fragmenten—chunks—en het inschakelen van deze optie kopieert de veldwaarde naar elk daarvan.

Concreet betekent dit dat bij author: "Marie Dupont" en inject_into_chunk: true, elke geïndexeerde chunk deze naam bevat. Een vraag als “Wat heeft Marie Dupont geschreven over netwerklatentie?” maakt dan kans om raak te schieten, omdat de naam voorkomt in de doorzochte inhoud. Zonder injectie vertrouwt dezelfde vraag alleen op de tekst van het rapport, waar de auteur misschien alleen op de voorpagina staat.

Schakel injectie dus in voor velden die context dragen—auteur, afdeling, jaar, categorie—en laat het uitgeschakeld voor administratieve velden zoals een intern ID, uploaddatum of validatiestatus, die alleen ruis zouden toevoegen.

Drie bewezen schema’s

Nuttige metagegevens worden niet in het abstract bedacht: ze vloeien voort uit de vragen die aan de database worden gesteld. Een technische documentatiebase organiseert zich rond product en versie, omdat de eerste vraag van een gebruiker bijna altijd “welke versie?” is:

{
  "fields": {
    "product": "Grok API",
    "version": "v1",
    "type": "reference",
    "language": "en"
  }
}

Een HR-kennisbase redeneert daarentegen per categorie en ingangsdatum, omdat het verkeerde antwoord daar vaak een ingetrokken beleid is:

{
  "fields": {
    "category": "hr-policy",
    "effective_date": "2026-01-01",
    "department": "all",
    "status": "active"
  }
}

Tot slot structureert een juridische base zich rond partijen, contracttype en vervaldatum, waardoor u overeenkomsten die bijna verlopen in één query kunt ophalen:

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

Een consistent schema behouden

Consistentie gaat altijd via dezelfde kanalen verloren, en een paar gewoonten volstaan om deze te behouden. Standaardiseer de formaten van veldnamen—snake_case, in het Engels, zonder talen te mengen. Beperk het aantal: vijf tot tien velden dekken de meeste behoeften; daarboven wegen de onderhoudskosten zwaarder dan de winst in relevantie. Ga verstandig om met inject_into_chunk, aangezien elk geïnjecteerd veld de chunks vergroot en daarmee de opslagkosten. Documenteer ten slotte het verwachte schema voor elke collectie in een bestand dat toegankelijk is voor het team: zodra meerdere personen het voeden, garandeert dat bestand, en niet het geheugen van de maker, de consistentie.

Belangrijkste punten

  • fields koppelt sleutel-waarde-metagegevens aan elk document
  • field_definitions op collectieniveau definiëren regels: required, unique, inject_into_chunk
  • De optie inject_into_chunk verbetert de zoekrelevantie door metagegevens aan de geïndexeerde inhoud toe te voegen
  • Standaardiseer uw metagegevensschema’s om de consistentie van de collectie te behouden