---
title: Manage source mappings
slug: '1640'
canonical_url: https://docs.coveo.com/en/1640/
collection: index-content
source_format: adoc
---
# Manage source mappings

Once you've [created a source](https://docs.coveo.com/en/3390#add-a-source) and [indexed](https://docs.coveo.com/en/204/) your content for the first time, you should review and customize the source [mappings](https://docs.coveo.com/en/217/).

The [Coveo Platform](https://docs.coveo.com/en/186/) uses these mappings to [index](https://docs.coveo.com/en/204/) important information about your content [items](https://docs.coveo.com/en/210/).
After you've [defined the mappings](#manage-mappings), you'll be able to configure critical aspects of your Coveo-powered search interface, such as [facets](https://docs.coveo.com/en/198/).

## About mappings

This section explains how mappings work, and how configuring them properly benefits your search interface.

For instructions on how to customize your mappings, jump to [Manage mappings](#manage-mappings).

### Item metadata

[mappings](https://docs.coveo.com/en/217/) define the information about your [items](https://docs.coveo.com/en/210/) that Coveo will store in your [index](https://docs.coveo.com/en/204/).
Coveo refers to this information as _[metadata](https://docs.coveo.com/en/218/)_, but other applications can give it different names, such as _properties_.
In all cases, though, the metadata comes in key-value pairs.

For example, when [indexing](https://docs.coveo.com/en/204/) PDF documents, you'll likely want to index metadata such as the title, author, creation date, and file size of each document.
Typically, the metadata of a PDF is accessible through a properties panel and looks as follows:

```text
Title: Project Planning
Author: John Smith
Created: 06/05/2023 10:34:21 AM
File Size: 988 KB
```

In this case, `Title`, `Author`, `Created`, and `File Size` are keys, while `Project Planning`, `John Smith`, `06/05/2023 10:34:21 AM`, and `988 KB` are values.
Keys are typically the same for all items of a certain type, but values often differ from one item to another.

### Coveo index

Your Coveo index also stores information in key-value pairs.
When indexing an item, Coveo takes its metadata values and stores them in containers called _fields_.
Fields may have names similar to your metadata keys, such as `title`, `author`, `date`, and `size`.

Coveo indexes metadata according to _mappings_ or _mapping rules_, i.e, instructions that tell Coveo to take the value of a certain key and to store it as the value of a certain field.

For example, when indexing PDF documents, you might want mappings that do the following:

[%header,cols="2"]
|===
|Take value of the ... key
|Store it in the ... field

|`Title`
|`title`

|`Author`
|`author`

|`Created`
|`date`

|`File Size`
|`size`
|===

### Automatically and manually created mappings

Depending on the type of content you index, Coveo may create mappings for you.
However, you should always review what's indexed and in which field.
You can customize your fields and rules as needed.

With [native sources](https://docs.coveo.com/en/1702#native-connectors), Coveo does the bulk of the work for you by creating default mappings when first indexing your content.
For example, with a YouTube source, there's no need to create fields for the video title, duration, and description, and then to create mappings to populate them with video metadata.
Since the metadata keys are always the same for all YouTube sources, Coveo knows what to expect and can do it automatically.

With [generic sources](https://docs.coveo.com/en/1702#generic-connectors), the metadata key naming scheme is likely unique to your content system.
As a result, Coveo doesn't know in advance what metadata to expect from your source, and which fields should be populated with this data.
You therefore need to manually create fields and mappings to index your content metadata.

However, to help you in this process, with most generic sources (Database, REST API, GraphQL API, Push, and Catalog), if Coveo finds a metadata key that matches an existing field name, it automatically indexes this metadata.
For example, if your item contains a `Price` metadata key, and you've already added a `price` field to your organization, Coveo automatically indexes the `Price` value in the `price` field.

With any source, however, you'll need to create or customize mappings when:

* A metadata key is different from the name of the desired destination field.

* You want all items to have the same field value.
For example, all items could have `Acme Computer Parts` in the `manufacturer` field.

* You want to [create a custom HTML Quickview for your items](https://docs.coveo.com/en/1847/).
This [quickview](https://docs.coveo.com/en/3311/) will be displayed in your search interface.

For more information about the stage of the [indexing pipeline](https://docs.coveo.com/en/184/) where mappings are applied, see [Mapping](https://docs.coveo.com/en/1893#mapping).

### Item type

When creating a mapping rule, you can specify one or multiple types of item your rule will apply to.
For example, when indexing YouTube content, you could choose to apply a rule to playlists only.

Typically, the item type is indexed as the value of the  `filetype`, `documenttype`, `mappingtype`, or `objecttype` fields.
So, before you customize your source mappings, use 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/)) to [inspect your source items](https://docs.coveo.com/en/2053#inspect-search-results) and note the value that Coveo indexed in these fields.

Then, when [customizing mappings](#manage-mappings), specifying this value will allow you to target all items of this type.

See [Source item types](https://docs.coveo.com/en/1965/) for details.


## About the `performFieldMappingUsingAllOrigins` setting

All source JSON configurations contain the `performFieldMappingUsingAllOrigins` setting at the root level of the JSON, which is available under the **All** tab.
When set to `true`, it allows Coveo to automatically index metadata if the metadata key in your content matches a Coveo field.
This setting allows you to skip the mapping creation step after you've created a source and its fields.

**Example**

You create a REST API source to index your company directory, which contains phone numbers under metadata key `phone`.
Then, you create a `phone` field.

Since the `performFieldMappingUsingAllOrigins` setting is set to `true`, Coveo automatically indexes the number under `phone` in the `phone` field.

> **Note**
>
> Although Coveo automatically indexes the metadata, no mapping rule appears in the **Edit mappings** panel.

The `performFieldMappingUsingAllOrigins` setting is especially useful in [generic sources](https://docs.coveo.com/en/1702#generic-connectors).
Therefore, it's set to `true` by default in Database, REST API, and GraphQL API sources created after January 10, 2024.
To set it to `true` in generic sources created before this date, [edit your source JSON configuration](https://docs.coveo.com/en/1685/), and then [launch a source rebuild](https://docs.coveo.com/en/3390#refresh-rescan-or-rebuild-sources).

In native sources, the `performFieldMappingUsingAllOrigins` setting is set to `false` by default, as [Coveo already automatically creates mappings for these sources](https://docs.coveo.com/en/1640#automatically-and-manually-created-mappings).
It's safer to leave it to `false`.
Setting `performFieldMappingUsingAllOrigins` to `true` in native sources comes with the risk of indexing irrelevant metadata and cluttering your index, which leads to a decrease in performance.
This may also lead to metadata being indexed in fields where it's not relevant, which in turn pollutes your facets with unwanted values.

Taking advantage of the `performFieldMappingUsingAllOrigins` setting to automatically index metadata may appear as a time-saving strategy.
However, if you do so, keep in mind that, to build search interfaces that offer an optimal experience, you must keep your fields and the information they contain clean and organized.
In other words, make sure you don't have redundant fields and that the information indexed in each field is adequate.

For example, let's say you already have a `jobtitle` field in your organization, and you want to index a Database source in which job titles are saved under the metadata key `work_title`.
You should definitely create a mapping rule to index the `work_title` metadata in the `jobtitle` field.
If you were to create a `work_title` field to take advantage of automatic metadata indexing, you would end up with a source populating the `jobtitle` field and another source indexing similar information in the `work_title` field.
Then, when creating a facet to display in your search interface, you would have to choose either of these fields.
As a result, the facet would show only a part of the job titles indexed by Coveo, and your search interface users wouldn't be able to filter your content optimally.

Similarly, let's say you already have the `title` field in your organization.
This field is used to index titles of PDF documents.
When creating a Database source to index an employee directory, you look at the content metadata and notice that job titles appear under the `title` metadata key.
With `performFieldMappingUsingAllOrigins` set to `true`, if you don't create a mapping rule, job titles will be automatically indexed in the `title` field.
A facet based on the `title` field would therefore show both job titles and document titles.
To avoid this, create a mapping rule to ensure that data under `title` is indexed somewhere else.

## Navigating the "Edit mappings" panel

The mappings panel is accessible from 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 of the Coveo Administration Console.
Click the [source](https://docs.coveo.com/en/246/) of which you want to manage the [mappings](https://docs.coveo.com/en/217/), and then click **Mappings** in the Action bar.

Alternatively, you can also access the panel [from the **View and map metadata** subpage](https://docs.coveo.com/en/m9ti0339#review-mapping-rules).

The panel consists of three tabs: **Common**, **Specific**, and **JSON**.

### "Common" and "Specific" tabs

The **Common** and the **Specific** tabs work in a similar way.
They show a list of fields and the corresponding mapping rule, that is, what Coveo will store in each field.
Both tabs also display information about the fields, that is, their [type](https://docs.coveo.com/en/1833#field-type) and whether some [options](https://docs.coveo.com/en/1833#field-options) are enabled.

The difference between the **Common** and the **Specific** tab is the items that the displayed rules apply to.
The **Common** tab shows rules that apply to all items of a source, while the **Specific** tab displays rules that apply to items of a specific type only.
When you select an item type on the left, the right part of the tab displays the corresponding fields and mapping rules.

For example, when indexing YouTube videos and playlists from your corporate channel, you could decide to apply a mapping rule to the playlists only.
This rule would appear on the **Specific** tab, when you'd click **playlist**.

![Playlist mapping rule | Coveo](https://docs.coveo.com/en/assets/images/index-content/youtube-playlist-mappings.png)

### "JSON" tab

The **JSON** tab shows the [source](https://docs.coveo.com/en/246/) [mapping](https://docs.coveo.com/en/217/) in JSON format.
Any modification made in the **Common** and **Specific** tabs automatically updates the **JSON** accordingly, and vice versa.

You can also review the mappings of a source on the **Mappings** tab of the [**Edit configuration with JSON** panel](https://docs.coveo.com/en/1685/).
Although the information is structured differently, the following instructions apply to both panels:

* [Edit the JSON configuration](https://docs.coveo.com/en/1685#edit-the-json-configuration)

* [Search for a keyword](https://docs.coveo.com/en/1685#search-for-a-keyword)

* [Add notes about your changes](https://docs.coveo.com/en/1685#add-notes-about-your-changes)

## Manage mappings

Once your source is done [indexing](https://docs.coveo.com/en/204/) your content for the first time, you can customize its [mappings](https://docs.coveo.com/en/217/).

Look at the metadata that Coveo might already have indexed, either on the [**View and map metadata**](https://docs.coveo.com/en/m9ti0339/) subpage or 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/)).
Think of the information that your search interface end users will find relevant when searching your content and of the [facets](https://docs.coveo.com/en/198/) you intend to add to your search interface.
Ask yourself:

. Has all the relevant metadata been indexed?

. Is the metadata indexed in the appropriate fields?

If the answer is _no_, you must customize your source mappings.

> **Important**
>
> If you use a [Catalog source](https://docs.coveo.com/en/l5if0244/) to [index](https://docs.coveo.com/en/204/) your [catalog data](https://docs.coveo.com/en/obcf0333/),
> don't define [source](https://docs.coveo.com/en/246/) [mappings](https://docs.coveo.com/en/217/) for the standard commerce [fields](https://docs.coveo.com/en/200/).
> 
> The
> [standard field mappings](https://docs.coveo.com/en/3139#commerce-standard-fields) defined in the [catalog configuration](https://docs.coveo.com/en/l5if0520/) will overwrite any [source](https://docs.coveo.com/en/246/) [mappings](https://docs.coveo.com/en/217/) for the standard commerce [fields](https://docs.coveo.com/en/200/).


. Determine whether you want to apply your mapping to some or all items of your source.
Check 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/)) for the properties of the items indexed by your source.
The [item type](#item-type) typically appears in the `filetype`, `documenttype`, `mappingtype`, or `objecttype` fields.

. To only apply the mapping to some items, add the item types you want.

**Click for item type addition procedure**
<details><summary>Details</summary>

. In the [**Edit mappings** panel](#navigating-the-edit-mappings-panel), click the **Add** dropdown menu, and then select **Item type**.

. In the **Add an Item Type** dialog, click the dropdown menu, and then select or create an [item](https://docs.coveo.com/en/210/) type.
Then, click **Add Type**.

</details>

. In the **Edit mappings** panel, select the appropriate [tab](#navigating-the-edit-mappings-panel), depending on the mapping that you want to add or edit.

. To add a mapping, click the **Add** dropdown menu, and then select **Mapping**.
To edit a mapping, click the rule that you want to edit, and then click **Edit** in the Action bar.

. Either way, in the panel that opens:

.. [[UnderField]]Under **Field**, select the field where Coveo will index your content metadata.
You can also [add a field](https://docs.coveo.com/en/1833#add-a-field) if needed.

.. [[UnderApplyTo]]Under **Apply to**, click **All items (common)** or **Specific item types** to determine to which items the mapping should apply.

.. [[UnderRules]]Under **Rules**, enter the mapping rule to apply.
See [Mapping rule syntax reference](https://docs.coveo.com/en/1839/) if needed.
If you enter more than one rule, [Coveo will evaluate them in the order they appear, until one of them yields a non-empty value](https://docs.coveo.com/en/1839#mapping-rule-evaluation).

.. Click **Apply mapping**.

. Back in the **Edit mappings** panel, click **Save and rebuild source** if you're done making changes.
Coveo will launch a [source](https://docs.coveo.com/en/246/) [rebuild](https://docs.coveo.com/en/2712/), which is necessary to apply your changes.

> **Tip**
>
> Alternatively, click **Save** to close the panel without launching a rebuild.
> This option is especially useful when you plan on making additional changes in the short term.
> Since a source with several millions of [items](https://docs.coveo.com/en/210/) may take weeks to rebuild, you'll save time and resources by rebuilding it only when necessary.

## Required privileges

You can assign privileges to allow access to specific tools in the [Coveo Administration Console](https://docs.coveo.com/en/183/).
The following table indicates the privileges required to view or edit elements of 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 and associated panels.
See [Manage privileges](https://docs.coveo.com/en/3151/) and [Privilege reference](https://docs.coveo.com/en/1707/) for more information.

> **Note**
>
> The **Edit all** privilege isn't required to create sources.
> When granting privileges for the [Sources](https://docs.coveo.com/en/1707#sources-domain) domain, you can grant a group or API key the **View all** or [**Custom**](https://docs.coveo.com/en/3151#custom-access-level) access level, instead of **Edit all**, and then select the **Can Create** checkbox to allow users to create sources.
> See [Can Create ability dependence](https://docs.coveo.com/en/3151#can-create-ability-dependence) for more information.

[%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
|===

## What's next?

Once your source is rebuilt, ensure that your [mappings](https://docs.coveo.com/en/217/) work as expected in the [Content Browser](https://docs.coveo.com/en/2865/).
In the [Fields tab](https://docs.coveo.com/en/1712#fields-tab) of your item properties, check that the metadata values have been properly indexed.
Adjust your mapping rules if necessary.