Search Results Carry Document Metadata
document.custom_metadata is now filled on every v3 search result.
Before, it was null unless the request set include.document_metadata: true. A search with no include block returned "custom_metadata": null on the document, which read as if the metadata sent with the upload had been lost. It had not: it was on the result's own custom_metadata. Now the same search returns the document's metadata without asking for it.
This applies to Query, Batch Query and Query All Collections. Query and Batch Query add no database read: the search already loads the row that holds the metadata. Query All Collections adds one small read, for the documents on the returned page only. The response grows by the size of the metadata it now carries.
Do I need to change anything?
- If you read the result's own
custom_metadata: nothing changes. - If you set
include.document_metadata: true: nothing changes. The setting is still accepted and now matches the default. - If you want the smallest response: set
include.document_metadata: false. The field is thennull, as it was before. A document's metadata can be up to 64 KB, and it repeats on every result that comes from that document. - If your code treats a
nulldocument.custom_metadataas "no flag was set": check it.nullnow means the document has no metadata, or the request switched the field off. A search that cannot load the metadata still answers, withnullin this field.
Two copies
A result carries the metadata in two places.
document.custom_metadatais the document's stored metadata, with the types you sent:"year": 2025comes back as the number2025, and"year": "2025"as the string. It is what Get Document returns. Only the document metadata endpoints change it.- The result's own
custom_metadatais the copy stored on the chunk when it was indexed. It also holds anything written through the chunk metadata endpoints.
The two copies start out equal. They differ after a chunk's metadata is edited: the edit shows on that chunk's own custom_metadata and never on document.custom_metadata. A file sent with "year": 2025 whose first chunk is then patched to "year": 1999 returns 1999 on that result and 2025 on its document. A document metadata edit goes the other way: patch the document to "year": 2026 and document.custom_metadata returns 2026, while each result's own custom_metadata keeps what it had. Filters and boosts match the search index, which follows both kinds of edit, so a filter on year: 2026 finds that document.
What stays the same
- A document with no metadata still returns
null, not an empty object. include.document: falsestill removes the wholedocumentobject, metadata included.- v2 search results have no
documentobject and are unchanged.
Same day: Metadata per File in One Upload, Uploaded Files Keep Their Names, Word Files Return Plain Text