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 with matching names in your Coveo organization to store the custom metadata values.

Note

With a Push source, you don’t need to add a source mapping if the name of your field matches the name of your custom metadata.

This article explains the rules to follow to push custom metadata correctly.

Reserved item body 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.

For more information about valid Push API item request bodies, see Item models.

Allowed metadata types

The Push API allows you to push item metadata of any primitive type, as well as arrays of primitives. Object types and dictionaries 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,
  "related_product": "Awesome Product",
  "tags": [
    "Relevancy",
    "Machine Learning",
    "Search"
  ],
  ...
}

Whether through automapping or manual mapping, custom metadata is mapped to a field in your index. You should ensure that each metadata value you push matches the type of the field it’s mapped to.

The possible field types are the following:

Type Field name example Value example Value for the Fields API

String

department
published

Sales
true

STRING

Integer 32

year

2025

LONG

Integer 64

timesinceepoch

1517341713150

LONG_64

Decimal

weight
length

5.25
3

DOUBLE

Date

date

2025-03-27

DATE

Vector

personalizationdata

[0.235, 0.1234, 0.789, 0.765]

VECTOR

For Boolean metadata, use String values in the item body of your Push API request (for example, "true" or "false") and map the metadata to a String field. If you use Boolean values 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 the Date type

The Date field type supports the following String formats:

  • "2002/01/31 11:53:12"

  • "2002-01-31 11:53:12.999Z"

  • "2002-01-31T11:53:12Z"

  • "1 Sep 85 09:54:48 GMT"

  • "12 Sep 85 09:54:48 GMT"

  • "Sun, 06 Nov 1994 08:49:37 GMT"

  • "Sun, 6 Nov 1994 08:49:37 GMT"

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

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

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

  • "Sun Nov 27 08:49:37 1994"

  • "Nov 29 2002 7:30PM"

When pushing metadata to a Date field, ensure your metadata values are strings that match one of these supported formats. If the target field can parse your metadata value, it converts it to the corresponding number of milliseconds since the Unix epoch (for example, 1517341713150).

Implicit field type conversion

A field can only hold values of a single type. If needed, the Coveo indexing pipeline tries to convert metadata values to the target field type. In some cases, the conversion may produce unexpected and meaningless values.

As a general rule, you should:

  1. Create fields with types that answer your needs (for example, the Date type or a numeric type for range queries and sorting).

  2. Push metadata values that the type of the target field supports.