Allowed Metadata Types

This is for:

Developer System Administrator

The Push API allows you to push any primitive type of item metadata (that is, Boolean, number, or string), as well as metadata in the form of arrays of primitives (for example, an array of strings). Object structured types aren’t supported.

Valid metadata values

{
  "is_frequently_updated": false,
  "number_of_likes": 144,
  "average_rating": 85.72,
  "related_product": "Awesome Product",
  "tags": [
    "Relevancy",
    "Machine Learning",
    "Search"
  ]
}

Invalid metadata values

{
  "author_profile": {
    "age": 42,
    "interests": [
      "Literature",
      "Hockey"
    ]
  },
  "table_of_content": [
    [
      "Act:",
      "I - Setup",
      "II - Conflict",
      "III - Resolution"
    ],
    [
      "Page Number:",
      "1",
      "17",
      "39"
    ]
  ]
}

Matching Metadata and Field Types

You should ensure that each metadata you push matches the type of the field (or fields) it populates in your index. The valid field types are:

  • String (for example, "Awesome Product")

  • Array of String (for multi-value fields) (for example, ["Relevancy","Machine Learning","Search"])

  • Integer 32 (for example, 3)

  • Integer 64 (for example, 314159265359)

  • Double (for example, 5.25)

  • Date (see About the Date Field Type)

  • Vector (for example, [0.235, 0.1234, 0.789, 0.765])

While you can push actual Boolean metadata (as well as arrays of numbers, Booleans, or even many primitive types), you should keep in mind that the Coveo indexing pipeline will attempt to convert such values when it populates their respective fields (see About Implicit Field Type Conversion).

You should always map Boolean metadata to String fields.

About the Date Field Type

The Date field type can be seen as a regular expression that recognizes several standard date and time string patterns:

  • "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 you push metadata you intend to map to a Date field, you should ensure that your date and time string matches one of the supported patterns. If the target Date field is able to parse your metadata, it will convert it to the corresponding number of milliseconds since Unix epoch.

Although not typically recommended, you can use the dateFormat property when creating or modifying a Date field to specify a single custom date and time string pattern that the field will recognize (see Creating Fields).

About Implicit Field Type Conversion

A given field can only hold a single type of value. As a result, when the Coveo indexing pipeline populates a field with metadata, it automatically attempts to cast the metadata value (or values) to the appropriate type, if required.

In the following table, each row contains a sample original metadata value along with each resulting field type conversion.

Original value String conversion Integer 32 conversion Integer 64 conversion Decimal Date conversion
"Hello world!" "Hello world" 0 0 0 Undefined
"314159265359" "314159265359" 626652751 314159265359 314159265359 Undefined
314159265359 "314159265359" 626652751 314159265359 314159265359 Undefined
"3.1415926535" "3.1415926535" 3 3 3.1415926535 Undefined
3.1415926535 "3.1415926535" 3 3 3.1415926535 Undefined
"19223372036854775807" "19223372036854775807" -1 9223372036854776000 19223372036854800000 Undefined
19223372036854775807 "19223372036854775807" -1 9223372036854776000 19223372036854800000 Undefined
00000000031415 "31415926535" 31415 31415 31415 Undefined
"00000000031415" "00000000031415" 31415 31415 31415 Undefined

"2017-11-16T13:56:12.999Z"

 "2017-11-16T13:56:12.999Z" 2017 2017 2017 1510840572000

"1 Sep 85 09:54:48 GMT"

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

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

 "Sun, 06 Nov 1994 08:49:37 GMT" 0 0 0 784111777000
"true" / true "true" 0 0 0 Undefined
"false" / false "false" 0 0 0 Undefined
["Hello", "World", "!"] "Hello;World;!" 0 0 0 Undefined
["Hello world!", true, 314159, 3.14159] "Hello world!;true;314159;3.14159" 3 3 3.14159 Undefined
Green The type conversion is perfectly valid.
Yellow The type conversion may be valid, depending on the scenario.
Red The type conversion is invalid.

You create a isfunny_integer Integer 32 field in your index (see Creating Fields). In your Push source, you create a mapping rule to populate this field with the isfunny metadata (see Manage the Mapping Configuration of a Source).

You use the Push API to add or update the following item in your Push source (see Add or Update a Single Item in a Push Source):

{
  "isfunny": true,
  "data": "<p>Example...</p>",
  "fileExtension": ".html"
}

When the Coveo indexing pipeline processes this item and applies the mapping rules of your Push source, it implicitly converts the isfunny metadata Boolean value (true) to the corresponding Integer 32 value (0) to populate the isfunny_integer field. Unfortunately, the converted value is meaningless.

A better idea would be to create a isfunny String field. Then, no mapping rule would be necessary, as the Coveo indexing pipeline automatically maps matching metadata and fields. Most importantly, the Boolean metadata value would be converted to the corresponding string value ("true"), which perfectly makes sense.