Skip to content

Amgix Documents

In Amgix a document is a basic searchable unit of information. If you want something to be found (returned in search results) it has to be stored as a document. Documents are organized in collections:

flowchart

    doc1[Doc 1] --> col[My Collection]
    doc2[Doc 2] --> col
    docX[...] --> col
    docN[Doc N] --> col

Let's look at the basic shape of the Document object:

{
  "id": "doc-123",
  "timestamp": "2026-06-21T12:00:00Z",
  "tags": ["news", "finance"],
  "name": "Quarterly report",
  "description": "Brief summary shown in search results",
  "content": "Full text used for indexing and search",
  "metadata": {
    "category": "report",
    "year": 2026
  },
  "custom_vectors": []
}
A few things to note here:

  • Amgix is opinionated about the shape of the document. By design, the top level properties you see above are all that Amgix will accept for the document. Additional properties must live in metadata (which is free-form), but more on that later.

Note

We realize that forcing a strict top level shape of the document is an unorthodox design decision by a search engine. Most allow you to use free-form documents. But we felt like the structure forces you to make very deliberate decisions on what you index/vectorize and how, keeping in mind the tradeoffs of storage size and performance. To date, we haven't seen a strong enough case, where the desired results couldn't be achieved by storing something in free-form metadata or by using a separate collection. We can be persuaded otherwise by a good use case.

  • id is required and has to be unique within the collection. Upserting a document with the id of an existing document will overwrite the stored document.
  • timestamp is required and expected to be in UTC timezone. It is used for automatic deduplication.

Automatic Timestamp Deduplication

Amgix does automatic timestamp deduplication on all documents. This serves multiple purposes:

  • It prevents you from accidentally overwriting a newer version of a document with an older one.
  • Your application code doesn't have to worry about order in which documents are uploaded - only about keeping the timestamp of the document in sync with the time when the document actually changed in your source system, like last_modified datetime.
  • It saves server resources from having to do embedding and indexing work on stale documents.
  • It allows you to do things like: re-upload your entire document set to a collection and only the changed documents will get processed and stored.

As long as your timestamps reflect your source system business logic of which document is newer Amgix will do the right thing.

  • name, description, and content are the only fields that can be indexed/vectorized for search purposes. But each one of these fields can be vectorized with multiple vector types. For example, you can index name for keyword search only, content with both keyword and dense model vectors, and keep description not indexed just for display purposes of your search results. All three are optional if you don't want the entry to be found via search and/or just want to store metadata in the collection. See our collections guide for more details.

  • tags is an optional array of strings that can be used for quickly filtering search results. Unlike metadata, tags are always indexed and ready to be filtered by. You can think of them as a filtering shortcut.

  • metadata is an optional free-form bag of key-value pairs where values can be strings, integers, floats, booleans, datetimes, objects, or arrays. By default metadata fields cannot be used for filtering, but if you need to filter by them, you can declare them as indexed at collection creation time (see collections guide for more details).

  • custom_vectors is an optional array and is how you supply custom dense or sparse vectors to be used for search if your collection was created with dense_custom or sparse_custom vector types (see collections guide for more details).

The shape for custom_vectors is as follows:

[
  {
    "vector_name": "my_custom_dense",
    "field": "description",
    "vector": [0.12, -0.34, 0.56, 0.78, ...]
  },
  {
    "vector_name": "my_custom_sparse",
    "field": "content",
    "vector": [[1, 0.8], [2, 0.6], [3, 0.4], ...]
  }
]

For sparse_custom types the vector is a list of index and weight tuples.

That is all there is to know about the Amgix Documents. Next, let's look at Amgix Collection Guide.