---
title: About the permanentid field
slug: '1913'
canonical_url: https://docs.coveo.com/en/1913/
collection: leverage-machine-learning
source_format: adoc
---
# About the permanentid field
> **Note**
>
> Use the `primaryid` [field](https://docs.coveo.com/en/200/) instead of the `permanentid` [field](https://docs.coveo.com/en/200/) when you need a stable and unique document identifier.
> See the [primaryid field and how it compares to permanentid and uniqueid](https://docs.coveo.com/en/pa9c0434/).

The `permanentid` [field](https://docs.coveo.com/en/200/) contains a value that permanently identifies each [item](https://docs.coveo.com/en/210/) within an organization.
The [field](https://docs.coveo.com/en/200/) value remains the same, even for an [item](https://docs.coveo.com/en/210/) that's indexed more than once with different [sources](https://docs.coveo.com/en/246/).
This [field](https://docs.coveo.com/en/200/) allows [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/) to learn user behavior on stable [item](https://docs.coveo.com/en/210/) IDs.

Before the addition of the `permanentid` [field](https://docs.coveo.com/en/200/), [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/) pages and [Coveo ML](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/) used the [`urihash`](https://docs.coveo.com/en/1913#about-the-urihash-field) [field](https://docs.coveo.com/en/200/) by default to identify [index](https://docs.coveo.com/en/204/) [items](https://docs.coveo.com/en/210/).

## permanentid field value

The method to get the `permanentid` [field](https://docs.coveo.com/en/200/) value may be different depending on the repository type:

* For most standard [sources](https://docs.coveo.com/en/246/), the `permanentid` [field](https://docs.coveo.com/en/200/) is:

** Based on the [item](https://docs.coveo.com/en/210/) URI, because it's an appropriate unique and permanent identifier.

** A 60 hexadecimal character hash of the [item](https://docs.coveo.com/en/210/) URI (to optimize [index](https://docs.coveo.com/en/204/) performance).

* For other repository types, such as **Google Drive** and **YouTube**, where one [item](https://docs.coveo.com/en/210/) can have more than one URI, the `permanentid` [field](https://docs.coveo.com/en/200/) is typically a hash of a string containing:

`(repository type identification) + (unique separator) + (source dependent unique item identifier)`

**Example**

In a **Box** [source](https://docs.coveo.com/en/246/), the [item](https://docs.coveo.com/en/210/) `permanentid` [field](https://docs.coveo.com/en/200/) value is a hash of the string:

```text
"https://www.box.com/" + "@@@" + file_id
```

where `file_id` is the Box unique identifier for each [item](https://docs.coveo.com/en/210/).

* For Salesforce [sources](https://docs.coveo.com/en/246/), the `permanentid` is automatically set by the Salesforce connector.

## Taking advantage of the permanentid field

The `permanentid` [field](https://docs.coveo.com/en/200/) usage should be mostly transparent, but you may need to perform some tasks to fully take advantage of the custom aspects benefits.

* Standard [source](https://docs.coveo.com/en/246/) types

The introduction and usage of the `permanentid` [field](https://docs.coveo.com/en/200/) is meant to be mostly transparent for standard [source](https://docs.coveo.com/en/246/) types:

** All standard [sources](https://docs.coveo.com/en/246/) automatically include the `permanentid` [metadata](https://docs.coveo.com/en/218/) and [field](https://docs.coveo.com/en/200/) [mapping](https://docs.coveo.com/en/217/).

** Since April 2017, a [JavaScript Search Framework](https://docs.coveo.com/en/187/) search page automatically detects the existence of the `permanentid` [field](https://docs.coveo.com/en/200/) for each clicked [item](https://docs.coveo.com/en/210/).
It sends this [field](https://docs.coveo.com/en/200/) and its value with each [Coveo Analytics event](https://docs.coveo.com/en/260/), in the `contentIdKey` and `contentIdValue` [metadata](https://docs.coveo.com/en/218/) [fields](https://docs.coveo.com/en/200/) respectively.
The page always sends the `urihash` [field](https://docs.coveo.com/en/200/) and its value.

** The [Coveo ML](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/) take the `contentIdKey` [field](https://docs.coveo.com/en/200/) and the `contentIdValue` [metadata](https://docs.coveo.com/en/218/) passed in [Coveo Analytics events](https://docs.coveo.com/en/260/) to identify each [item](https://docs.coveo.com/en/210/) to learn from, using the `urihash` as a fallback.
The transition from the `urihash` to the `permanentid` [field](https://docs.coveo.com/en/200/) is therefore automatic.
Within an [index](https://docs.coveo.com/en/204/) or even a [source](https://docs.coveo.com/en/246/), [items](https://docs.coveo.com/en/210/) may be identified using either [field](https://docs.coveo.com/en/200/).

The [models](https://docs.coveo.com/en/1012/) can map older [events](https://docs.coveo.com/en/260/), which contain only the `urihash` [field](https://docs.coveo.com/en/200/), to newer ones with both the `urihash` and `permanentid` [fields](https://docs.coveo.com/en/200/).
This allows each [item](https://docs.coveo.com/en/210/)'s click history to be preserved through the transition.

> **Note**
>
> Following the transition from the `urihash` to the `permanentid` [field](https://docs.coveo.com/en/200/), your users may experience a minor and temporary degradation of [Coveo ML](https://docs.coveo.com/en/188/) [Automatic Relevance Tuning (ART)](https://docs.coveo.com/en/1013/) and [Content Recommendation (CR)](https://docs.coveo.com/en/1016/) [model](https://docs.coveo.com/en/1012/) performance, but only if you push custom [Coveo Analytics](https://docs.coveo.com/en/182/) click [events](https://docs.coveo.com/en/260/) that don't include both the `urihash` and `permanentid`.
> 
> This is because [items](https://docs.coveo.com/en/210/) whose unique identifier suddenly changes will appear as new [items](https://docs.coveo.com/en/210/) to [Coveo ML](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/).
> With time, however, new [events](https://docs.coveo.com/en/260/) on these [items](https://docs.coveo.com/en/210/) will accumulate, rebuilding their usage history and allowing [Coveo ML](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/) to learn from them again.

* [[PushAPI]]Custom [sources](https://docs.coveo.com/en/246/) (Push API)

For custom [sources](https://docs.coveo.com/en/246/) populated through the Push API, when the URI isn't a unique identifier and you want to allow [Coveo ML](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/) to learn usage of pushed [items](https://docs.coveo.com/en/210/), you can:

. Push [metadata](https://docs.coveo.com/en/218/) that uniquely and permanently identifies each pushed [item](https://docs.coveo.com/en/210/).

The content of the [metadata](https://docs.coveo.com/en/218/) can be anything such as a URI or a GUID, as long as it's unique and never changes.

> **Note**
>
> Using an alphanumeric string of at most 60 characters (without spaces) optimizes [index](https://docs.coveo.com/en/204/) performance.
> However, you can use any value you want.
> Using a value that isn't hashed can help with troubleshooting.

. [Map](https://docs.coveo.com/en/1640/) this [metadata](https://docs.coveo.com/en/218/) to the `permanentid` [field](https://docs.coveo.com/en/200/).

## About the urihash field

Before the addition of the `permanentid` [field](https://docs.coveo.com/en/200/), the `urihash` [field](https://docs.coveo.com/en/200/) was used to identify [index](https://docs.coveo.com/en/204/) [items](https://docs.coveo.com/en/210/).

The value of the `urihash` [field](https://docs.coveo.com/en/200/) for a given [item](https://docs.coveo.com/en/210/) is based on the [item](https://docs.coveo.com/en/210/)'s URI value.
The [item](https://docs.coveo.com/en/210/)'s URI is [hashed](https://en.wikipedia.org/wiki/Hash_function) to create a standardized `urihash` value.

For some [sources](https://docs.coveo.com/en/246/), such as a [repository](https://docs.coveo.com/en/2739/) that allows to share [items](https://docs.coveo.com/en/210/), an [item](https://docs.coveo.com/en/210/) could have more than one URI, and therefore more than one `urihash` [field](https://docs.coveo.com/en/200/) value.
This can cause [Coveo ML](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/) to interpret these values as distinct [items](https://docs.coveo.com/en/210/) when they actually refer to the same [item](https://docs.coveo.com/en/210/).

**Example**

In a Box [source](https://docs.coveo.com/en/246/), the [item](https://docs.coveo.com/en/210/) URI includes the Box user ID, so a shared file or folder has many URIs.
The `permanentid` [field](https://docs.coveo.com/en/200/) value is based on the Box `file_id` value, which remains the same even when an [item](https://docs.coveo.com/en/210/) is shared and accessible with various paths by various users.