Custom metadata

This is for:

Developer System Administrator

If Coveo doesn’t provide standard metadata for a specific piece of information about an item, you can create and push your own custom metadata key-value pairs along with the items you add or update in a Push source. To do this, create fields to store the custom metadata values.

Tip

Name your field the same as your metadata key to benefit from automatic mapping and avoid creating mappings manually.

This article explains the rules to follow when pushing custom metadata key-value pairs.

Reserved keys

When you push items to a Push source using the Coveo Push API, you include the metadata key-value pairs in the HTTP request body. You can include as many metadata key-value pairs as you need, as long as each key name is unique.

Don’t use the following key names for your custom metadata or fields. They’re reserved by Coveo for specific purposes:

  • compressedBinaryData

  • compressedBinaryDataFileId

  • compressionType

  • data

  • documentId

  • fileExtension

  • orderingId

  • parentId

  • permissions

Metadata key names are case-insensitive. For example, mykey, MyKey, and myKey are all considered identical. This means you can’t use a reserved item body key for custom metadata, even if you change its case.

Allowed metadata value types

Whether through automatic mapping or manual mapping, metadata is mapped to a field in your index. Each metadata value in the items you push must be compatible with the field type it’s mapped to.

You can create fields from the Coveo Administration Console Fields (platform-ca | platform-eu | platform-au) page or by using the Field API. The following table lists the field type equivalences between the Administration Console and the Field API.

Field type
(Administration Console)		 Field type
(Field API)		 Example values

String

STRING

Sales
true

Integer 32

LONG

2025

Integer 64

LONG_64

1517341713150

Decimal

DOUBLE

5.25
3

Date

DATE

2025-03-27

Vector

VECTOR

[0.235, 0.1234, 0.789, 0.765]
About Boolean metadata

To index Boolean metadata values, use the String field type. If you use Boolean values (true or false) in your Push API request and the metadata is mapped to a String field, the Coveo indexing pipeline converts the Boolean values to their corresponding String values ("true" or "false").

About arrays

Coveo supports arrays of string values using the Multi-value facet field option.

About date string formats

Coveo supports numerous metadata date string formats, subject to the following rules:

  • When no time zone is specified in the metadata date value, UTC is assumed.

  • When no time fragment is provided in the metadata date value, 00:00:00.000 UTC is assumed.

  • Fractional seconds (milliseconds) specified in the metadata date value are stripped during parsing. For example, 15:01:03.895 becomes 15:01:03.000.

  • By default, dates are displayed in search interfaces in the user’s time zone.

The following are examples of supported metadata date values and the associated field values for a user in the America/Toronto time zone.

Metadata date string examples Field value ("America/Toronto" time zone)

2025-03-27

2025-03-26 20:00:00.000

2002/01/31 11:53:12

2002-01-31 06:53:12.000

2002-01-31 11:53:12.999Z

2002-01-31 06:53:12.000

2002-01-31T11:53:12Z

2002-01-31 06:53:12.000

1 Sep 85 09:54:48 GMT

1985-09-01 05:54:48.000

12 Sep 85 09:54:48 GMT

1985-09-12 05:54:48.000

Sun, 06 Nov 1994 08:49:37 GMT

1994-11-06 03:49:37.000

Sun, 6 Nov 1994 08:49:37 GMT

1994-11-06 03:49:37.000

Mon, 01-Jan-70 12:00:00 GMT

1970-01-01 07:00:00.000

Sunday, 06-Nov-94 08:49:37 GMT

1994-11-06 03:49:37.000

Sunday, 02/17/02 20:01:03 EST

2002-02-17 20:01:03.000

Sun Nov 27 08:49:37 1994

1994-11-27 03:49:37.000

Nov 29 2002 7:30PM

2002-11-29 14:30:00.000

When ingesting content using the Push API or the Stream API, wrap date string values in double quotes (for example, "2025-03-27").

About dictionary fields

Dictionary fields are string or numeric fields that can contain multiple key-value pairs. They’re not a field type but rather a capability that you can enable when creating or updating a field via the Field API. See Dictionary fields for more information.

About dynamic fields

Dynamic fields are temporary fields created by a query function to store the value resulting from the calculation. For example, geolocalized search results and discounted prices are operations that require dynamic fields.

Since dynamic fields exist only for the duration of the query execution, they’re not listed on the Fields (platform-ca | platform-eu | platform-au) page, and dynamic isn’t a proper field type.

Note

Complex object types aren’t supported.
Example of valid metadata values in a Push API request body 
{
  ...
  "is_frequently_updated": "false",
  "number_of_likes": 144,
  "average_rating": 85.72,
  "last_updated": "Sunday, 02/17/02 20:01:03 EST",
  "related_product": "Awesome Product",
  "tags": [
    "Relevancy",
    "Machine Learning",
    "Search"
  ],
  ...
}