---
title: Index metadata
slug: o3ca0547
canonical_url: https://docs.coveo.com/en/o3ca0547/
collection: index-content
source_format: adoc
---
# Index metadata
--
Once you've [created a source](https://docs.coveo.com/en/3390#add-a-source) and it's done [indexing](https://docs.coveo.com/en/204/) your content for the first time, you should focus your attention on the [metadata](https://docs.coveo.com/en/218/) you want to index.
This will later allow you to configure critical aspects of your Coveo-powered [search interface](https://docs.coveo.com/en/2741/), such as [facets](https://docs.coveo.com/en/198/).

![Facets on a sports equipment retailer website | Coveo](https://docs.coveo.com/en/assets/images/index-content/index-metadata-facets.png)

For example, on a sports equipment retailer website, facets could let customers search by color and brand.
Selecting a color would narrow the products down to only those matching this criteria.

It's therefore crucial to index your metadata, as this impacts your end user's experience.
--

## From metadata to facets

Facets are based on the content indexed in the [fields](https://docs.coveo.com/en/200/) of your [items](https://docs.coveo.com/en/210/).
This means that, before you create a facet for a specific piece of metadata, you must ensure that this metadata is indexed in a field.

In general, there are three steps to using content repository data as facet values in a Coveo-powered search interface:

1 [Extract the metadata](#step-1-extract-metadata) you want to use as a facet from your content repository.

2 [Create a source mapping and a field](#step-2-create-a-source-mapping-and-a-field) to store the extracted metadata.

3 [Reference the field in a facet](#step-3-reference-the-field-in-a-facet).

![From metadata to facet | Coveo](https://docs.coveo.com/en/assets/images/index-content/from-metadata-to-facet.gif)

## Step 1: Extract metadata

--
Extracting metadata begins with determining what piece of information in your content repository you want to use as filtering criteria.
You should be able to look at your content repository items and identify the metadata values you want to index.
Typically, each repository item (or each item in a subset of your repository items) will expose a value (or a set of values) for a given metadata.

![Extract metadata | Coveo](https://docs.coveo.com/en/assets/images/index-content/metadata-mapping-field-facet-extract-metadata.png)

For example, if a portion of your company's website is dedicated to software documentation, you might want to index the `audience` metadata of those pages, where each page would contain values such as `User`, `System Administrator`, or both.

You might need to configure your source to extract custom metadata from your content repository.
However, since Coveo sources automatically extract basic metadata as well as metadata that's inherent to the source type, you should check if the metadata you want to use is already extracted before configuring your source to extract custom metadata.

![View and map metadata subpage | Coveo](https://docs.coveo.com/en/assets/images/index-content/view-metadata-with-mapped-and-unmapped-meta.png)

To determine which metadata is automatically extracted, access the **View and map metadata** subpage.
On the [**Sources**](https://platform.cloud.coveo.com/admin/#/orgid/content/sources/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/sources/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/sources/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/sources/)) page, click your source, and then click **More** > **View and map metadata**.

Review the **Metadata Name** and **Example Value** columns to identify whether the metadata you want to use is already extracted.
You can expand a metadata row to show additional extracted values.

If the desired metadata is already extracted, you can move on to [step 2](#step-2-create-a-source-mapping-and-a-field).
If the desired metadata isn't already extracted, configure your source to extract custom metadata.
--

### Extract custom metadata

The way to extract custom metadata varies from one source type to the next.
The following table lists methods you can use with common source types:

[%header,cols="1,5"]
|===
^|Source type
|Custom metadata extraction methods

^|[Push API](https://docs.coveo.com/en/1546/)
|Define metadata key-value pairs in the `addOrUpdate` section of the PUT request payload used to [upload push operations to an Amazon S3 file container](https://docs.coveo.com/en/90#step-2-upload-the-content-update-into-the-file-container).

^a|[REST API](https://docs.coveo.com/en/1896/)  
and  
[GraphQL API](https://docs.coveo.com/en/n6gh2329/)
|In the JSON configuration ([REST API](https://docs.coveo.com/en/1525/) \| [GraphQL API](https://docs.coveo.com/en/o1ae7549/)) of the source, define metadata names ([REST API](https://docs.coveo.com/en/1525#metadata-object) \| [GraphQL API](https://docs.coveo.com/en/o1ae7549#metadata-object)) and specify where to locate the metadata values in the JSON API response Coveo receives.

^|[Database](https://docs.coveo.com/en/1885/)
|Add [`<CustomField>` elements](https://docs.coveo.com/en/l15b4451#customfields) in the XML configuration.
Each element defines a metadata name and the database field to use to populate the metadata with.

^|[Web](https://docs.coveo.com/en/malf0160/)
a|* Configure [web scraping](https://docs.coveo.com/en/2767/) configurations that contain [metadata extraction rules](https://docs.coveo.com/en/mc1f3573#metadata-to-extract) using CSS or XPath selectors.

* Extract metadata from [JSON-LD `<script>` tags](https://docs.coveo.com/en/mc1f0219#indexjsonldmetadata-boolean).

^|[Sitemap](https://docs.coveo.com/en/1967/)
a|* Extract [metadata included in the XML sitemap file](https://docs.coveo.com/en/2656/).

* Configure [web scraping](https://docs.coveo.com/en/2767/) configurations that contain [metadata extraction rules](https://docs.coveo.com/en/mahe0350#metadata-to-extract) using CSS or XPath selectors.

* Extract [JSON-LD `<script>` tag](https://docs.coveo.com/en/1967#extract-json-ld-metadata) metadata.

* Extract `<meta>` tag content using the [`IndexHtmlMetadata` JSON parameter](https://docs.coveo.com/en/o2ta0401/).
|===

For the complete list of source types, see [Choosing the right connector](https://docs.coveo.com/en/1702#choosing-the-right-connector).

As you add custom metadata extraction configurations, [rebuild your source](https://docs.coveo.com/en/2039#rebuild) and review the **View and map metadata** subpage to ensure that the metadata is being extracted as expected.

### About default field values

_Default fields_ are fields that Coveo creates for each item in your source.
These fields are used to store metadata that is generally automatically extracted from your content repository.
You can find a list of the default fields in [Field origin](https://docs.coveo.com/en/1833#field-origin).

Default fields can be filled at three different stages of the [Coveo indexing pipeline](https://docs.coveo.com/en/1893/):

. During the crawling or push process
. When applying a pre-conversion indexing pipeline extension (IPE)
. When applying a post-conversion IPE

The metadata saved in a field during the crawling/push process may be overwritten by the converter at the [processing stage](https://docs.coveo.com/en/1893#processing).
For example, let's say the `author` field is populated during the crawling process with `Mary Johnson`.
Then, when the converter processes the item, it may find a different value for the `author` field in the content of the item, such as `John Smith`, under the `author` metadata.
The converter will then overwrite the `author` field with this new value, and `John Smith` will be indexed in the `author` field.

However, if you want to keep the value saved at an earlier stage, you can [specify it in your mapping rule](https://docs.coveo.com/en/1839/).
For example, in the above scenario, the `%[author:crawler]` mapping rule would ensure that the `author` field is populated with `Mary Johnson`.

Conversely, fields populated with a post-conversion IPE are not overwritten by the converter, as the post-conversion IPE step occurs after the processing stage.

Values indexed in the following default fields can't be overwritten at all: `orderingid`, `primaryid`, `rowid`, `source`, `transactionid`, and `urihash`.
It is strongly discouraged to use a system field as a [dictionary field](https://docs.coveo.com/en/2036/).

#### Custom metadata you're extracting isn't showing on the View and map metadata subpage?

When you visit the **View and map metadata** subpage, Coveo creates a summary of the available metadata, based on a sample of the indexed content at that time.
The sample might not yet include your custom metadata if you visit the **View and map metadata** subpage at the beginning of a build or rebuild operation.
It may only be a matter of time before the sample includes your custom metadata.
During a rebuild, click **Refresh** at the top of the **View and map metadata** subpage to get an updated summary.

If only a small subset of the entire content contains the custom metadata you would like to extract, the sample might not even include it at the end of the rebuild.

Not seeing your custom metadata on the **View and map metadata** subpage doesn't prevent you from creating your mapping and field.
[Step 2](#step-2-create-a-source-mapping-and-a-field) guides you accordingly.

## Step 2: Create a source mapping and a field

--
![Create mapping | Coveo](https://docs.coveo.com/en/assets/images/index-content/mapping-incoming-metadata.gif)

Metadata values must be indexed in fields.
The bridge between a piece of metadata and a field is a source [mapping](https://docs.coveo.com/en/217/).
A mapping consists mainly of two pieces of information:

* A _mapping rule_ (which specifies an incoming piece of metadata).

* A reference to the _receiving field_.  
The actual receiving field may already exist.
You can also create it as part of the mapping creation process.

A source mapping instructs the [Coveo Platform](https://docs.coveo.com/en/186/) which field will receive the incoming metadata.

> **Note**
>
> For a more detailed explanation of how mappings work, see [About mappings](https://docs.coveo.com/en/1640#about-mappings).
--

If your metadata appears on the **View and map metadata** subpage, you can [create a mapping directly from there](#create-a-mapping-for-metadata-appearing-on-view-and-map-metadata).
Otherwise, you can use the [fallback method](#fallback-method-for-creating-a-mapping) to create your mapping.

### Create a mapping for metadata appearing on View and map metadata

. On the **View and map metadata** subpage, if the metadata you want to index doesn't already show as **indexed**, click it.

> **Note**
>
> If your metadata shows as **indexed**, a mapping and a field already exist for that metadata.
> To determine which field the metadata is indexed in or to edit the mapping, see [Review indexed metadata](#review-indexed-metadata).

. Click **Add to index** in the Action bar.

. In the **Apply a mapping...** panel, unless you already have a field that you want to use, click **Add field**.

![Adding mapping and field | Coveo](https://docs.coveo.com/en/assets/images/index-content/add-mapping-and-field.png)

. In the **Add a Field** panel, enter a name for the field and configure its settings.
For example, if you're indexing the `audience` metadata of a document and the audience can contain multiple values, select **Multi-Value Facet**.

> **Note**
>
> Apart from the **Type** setting, you can [edit the field options](https://docs.coveo.com/en/1833#add-a-field) later if needed.

. When you're done, click **Add field**.

. Back in the **Apply a mapping...** panel, use the **Select an option** dropdown menu to select the field you just created.

. Under **Apply to**, leave the default **All items (common)** value.

> **Note**
>
> You can [edit this setting](https://docs.coveo.com/en/1640#manage-mappings) later if you decide to apply the mapping to only a subset of the items of your source.

. Under **Rules**, Coveo suggests a [mapping rule](https://docs.coveo.com/en/1839/) (for example, `%[audience]` or `%[audience:crawler]`) based on the metadata name you selected.
You can edit this rule now [or later](https://docs.coveo.com/en/1640#manage-mappings) if needed.

. Click **Apply mapping**.

. [Rebuild your source](https://docs.coveo.com/en/2039#rebuild).

### Fallback method for creating a mapping

. On the [**Sources**](https://platform.cloud.coveo.com/admin/#/orgid/content/sources/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/sources/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/sources/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/sources/)) page, click your source, and then click **Mappings** in the Action bar.

. Follow the **Edit mappings** panel [mapping creation procedure](https://docs.coveo.com/en/1640#manage-mappings).

### Review indexed metadata

When the **View and map metadata** subpage shows metadata as **indexed**, this means a mapping and a field already exist for that metadata.

To determine which field the metadata is indexed in

. In the **View and map metadata** subpage, click the metadata, and then click **View mappings** in the Action bar.

. In the **Edit mappings** panel, in the **Rule** column, locate the mapping rule that references your metadata name (for example, `%[audience]` or `%[audience:crawler]`).

The associated field is shown in the **Field** column.

To edit that mapping

. Click the mapping, and then click **Edit** in the Action bar.

. Perform the necessary changes, and then click **Apply mapping**.

. [Rebuild your source](https://docs.coveo.com/en/2039#rebuild).

## Step 3: Reference the field in a facet

Once your source is rebuilt, ensure that your [mappings](https://docs.coveo.com/en/217/) work as expected in the [**Content Browser**](https://platform.cloud.coveo.com/admin/#/orgid/content/browser/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/browser/)).
In the [Fields tab](https://docs.coveo.com/en/1712#fields-tab) of your item properties, check that the desired metadata values have been properly indexed.
Adjust your mapping rules if necessary.

The process of creating a facet, and other ways you can use indexed metadata in a search interface is covered in the [Build a search UI](https://docs.coveo.com/en/3366/) section.

## Required privileges

The following table lists the privileges required to perform the actions described in this article.

[%header,cols="50%, 18%, 20%, 25%"]
|===
|Actions
|Service
|Domain
|Required access level

.3+|View sources, view source update schedules, and subscribe to source notifications
.2+|Content
|Fields
.3+|View

|Sources
|Organization
|Organization

.3+|Edit sources, edit source update schedules, and edit source mappings
|Organization
|Organization
|View
.2+|Content
|Fields
.2+|Edit
|Sources

.4+|View and map metadata
.2+|Content
|Source metadata
.3+|View

|Fields
|Organization
|Organization

|Content
|Sources
|Edit
|===