Index metadata

This is for:

Developer System Administrator

Once you’ve created a source and it’s done indexing your content for the first time, you should focus your attention on the metadata you want to index. This will later allow you to configure critical aspects of your Coveo-powered search interface, such as facets.

Facets on a sports equipment retailer website | Coveo

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 of your items. This means that if you want to create a facet for a specific 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 you want to use as a facet from your content repository.

2 Create a source mapping and a field to store the extracted metadata.

3 Reference the field in a facet.

From metadata to facet | Coveo

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

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 Metadata subpage | Coveo

To determine which metadata is automatically extracted, access the View Metadata subpage. On the Sources (platform-ca | platform-eu | platform-au) page, click your source, and then click More > View 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. If the desired metadata isn’t already extracted, you need to 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:

Source type Custom metadata extraction methods

Push API

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.

REST API
and
GraphQL API

In the JSON configuration (REST API | GraphQL API) of the source, define metadata names (REST API | GraphQL API) and specify where to locate the metadata values in the JSON API response Coveo receives.

Database

Add <CustomField> elements in the XML configuration. Each element defines a metadata name and the database field to use to populate the metadata with.

Web

Sitemap

For the complete list of source types, see Native and generic connectors.

As you add custom metadata extraction configurations, rebuild your source and review the View Metadata subpage to ensure that the metadata is being extracted as expected.

Custom metadata you’re extracting isn’t showing on the View Metadata subpage?

When you visit the View 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 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 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 Metadata subpage doesn’t prevent you from creating your mapping and field. Step 2 guides you accordingly.

Step 2: Create a source mapping and a field

Create mapping | Coveo

Metadata values must be indexed in fields. The bridge between a piece of metadata and a field is a source mapping. 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 which field will receive the incoming metadata.

Note

For a more detailed explanation of how mappings work, see About mappings.

If your metadata appears on the View Metadata subpage, you can create a mapping directly from there. Otherwise, you can use the fallback method to create your mapping.

Create a mapping for metadata appearing on View Metadata

  1. On the View 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.

  2. Click Add to index in the Action bar.

  3. 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

  4. 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 settings later if needed. For more details on the field settings, see String options and Advanced settings.

  5. When you’re done, click Add field.

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

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

    Note

    You can edit this setting later if you decide to apply the mapping to only a subset of the items of your source.

  8. Under Rules, Coveo suggests a mapping rule (for example, %[audience] or %[audience:crawler]) based on the metadata name you selected. You can edit this rule now or later if needed.

  9. Click Apply mapping.

  10. Rebuild your source.

Fallback method for creating a mapping

  1. On the Sources (platform-ca | platform-eu | platform-au) page, click your source, and then click More > Manage mappings in the Action bar.

  2. Follow the Edit the Mappings of a Source panel mapping creation procedure.

Review indexed metadata

When the View 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

  1. In the View Metadata subpage, click the metadata, and then click View mappings in the Action bar.

  2. In the Edit the mappings of a source 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

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

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

  3. Rebuild your source.

Step 3: Reference the field in a facet

Once your source is rebuilt, ensure that your mappings work as expected in the Content Browser (platform-ca | platform-eu | platform-au). In the 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 section.

Required privileges

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

Actions Service Domain Required access level

View sources, view source update schedules, and subscribe to source notifications

Content

Fields

View

Sources

Organization

Organization

Edit sources, edit source update schedules, and view the View Metadata subpage

Content

Fields

Edit

Sources

Content

Source metadata

View

Organization

Organization