primaryid field

This is for:

Developer System Administrator

The primaryid field contains a globally unique ID that identifies an item across your whole Coveo organization. The primaryid encodes both the source and the index, so two items with the same uri or permanentid will never collide.

primaryid points to exactly one item, no matter how it was indexed in your Coveo organization. It’s meant to identify an exact item the index returned after all security filters and query pipeline rules have been applied.

primaryid versus permanentid and uniqueid

Coveo indexes every item with several identifiers. The three main identifiers are primaryid, permanentid, and uniqueid. These item IDs point to the same logical document in the index, but each ID has a specific purpose and scope. primaryid is mainly for external use, permanentid is used mainly for Coveo Machine Learning, and uniqueid is used internally by the Coveo indexing system.

The following table summarizes the key differences between the item IDs, in which context the IDs are safe to use, and whether they survive reindexing or different sources:

Identifier Visibility and API usage Scope and stability Notes

uniqueid

Returned in query results. Cannot be queried.

Unique within an index as long as the document is indexed using a single source. If the same document is indexed in multiple sources, each instance has its own uniqueid.

Used by the index as the document key. Not meant to be reliable for external use.

permanentid

Returned in query results and Coveo Analytics events.

Stable across versions of the same item. Stable across sources if the same item was indexed.

Useful for item grouping, Coveo Machine Learning (Coveo ML), or product-level analytics. Not globally unique or security-aware.

If two items differ only by permissions, they will have the same permanentid. This can lead to permission or authorization issues.

primaryid

Returned in the API responses.[1]

Unique within an organization, stable, and security-filtered.

Safest choice for referencing or persisting a item exactly as in search results.

1. The Search API, PR API, and Answer API return the primaryid field in their responses.

Best practices

Choosing which item ID to use depends on what you’re doing with the item data. Picking the right item ID for your integration helps to avoid collisions, stale references, or permission mismatches.

primaryid

Use primaryid when you need a one-to-one reference to a specific, security-filtered item. For example, to:

  • fetch passages or snippets.

  • store or cache the search results.

  • link securely to a item.

  • build pipelines or exports that must not drift from search results.

permanentid

Use permanentid to group or analyze multiple representations of the same item, such as versions, languages, or product variants. It’s suitable for publicly available items for which access control isn’t a concern.

uniqueid

Use the primaryid instead. uniqueid is an internal Coveo index identifier and isn’t reliable for use in external implementations.