Create fields with the API

This is for:

In this article

Sample request

A field is an index-wide container that can hold a single type of data (Long 32, Long 64, Double, Date, or String). You can use a field to store and retrieve specific information about items in your index. source mappings can contain rules to populate fields with metadata when the Coveo indexing pipeline processes an incoming item. See Manage the mapping configuration of a source for details on this topic.

Leading practices

In general, a given field should have a single purpose (although concatenating metadata into a single field can be legitimate in some use cases).

For example, rather than creating a field named product in your Coveo organization and defining mapping rules in a source to populate that field with a concatenated string containing the unique identifier of a product along with its corresponding name (for example, 1234-abcd|My Product Name), you should consider creating a distinct field for each of those metadata (for example, a productid field and a productname field).
When creating new fields, you should use a coherent field naming convention that takes into account the names of the existing standard, source-specific, and custom fields in your index. You should somehow prefix custom source-specific fields (for example, mysrc_productid, mysrc_productname).

Use the Create a batch of fields operation to create one or more fields in a Coveo organization. Alternatively, you can add fields from the Coveo Administration Console.

Request template

POST https://platform.cloud.coveo.com/rest/organizations/<MyOrganizationId>/indexes/fields/batch/create HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>

Payload

[
  {
    "name": <MyFieldName>,
    "description": <MyFieldDescription>,
    "type": <"LONG"|"LONG_64"|"DOUBLE"|"DATE"|"STRING">,
    "dateFormat": <MyDateFormat>,
    <FieldOption>: <true|false>
  }
]

In the request path, replace <MyOrganizationId> with your organization ID.

In the Authorization HTTP header, replace <MyAccessToken> with an access token that grants the Organization > Edit and Fields > Edit privileges. See Create an API key, Get the privileges of an access token, and Get your Coveo access token for details.

In the request body, for each element you include in the array:

Replace <MyFieldName> with the desired field name, which must be a string that matches the following regular expression: ^([a-z][a-z0-9_]{0,254})$. In other words, a field name must:
- Start with a lowercase alphabetic character.
- Contain only lowercase alphabetic characters, numeric characters, and/or underscore characters.
- Be at most 255 characters long.
Field name examples
Valid field names:
"productname" "productname1" "product_name" "product_name1" "p__r0ductn4m3_"
Invalid field names:
"Productname" "productName" "1productname" "_productname" "@productname" "product name" "productname "
Note

You can’t change the name of a field once it’s been created.
Replace <MyFieldDescription> with a string explaining the purpose of the field, as well as who created it and when. Adding a description is optional, but recommended.
Replace <"LONG"|"LONG_64"|"DOUBLE"|"DATE"|"STRING"> with the enum value that best corresponds to the data type you intend to populate the field with. For a Boolean field, use the STRING type.

Note

You can’t change the type of a field once it’s been created.

When creating a DATE type field, if you want to ensure that the field only recognizes a specific, non-standard date and time string format, replace <MyDateFormat> with the desired pattern. The dateFormat property in your request body is otherwise optional.

By default, a DATE type field recognizes several standard date and time string formats.

Specifying a value for the dateFormat property makes the DATE type field recognize only the specified pattern.

Moreover, it’s important to keep in mind that fields are index-wide containers. This implies that if you specify a custom dateFormat for a field that’s targeted by the mappings of several distinct non-Push sources, chances are that the Coveo indexing pipeline will no longer be able to populate this field when it processes items from those sources, as the corresponding mapped metadata for these items will very likely not be in the specified date and time format.

Therefore, you should typically not specify a custom dateFormat property value for a field.

For each field option whose default value you want to change, replace <FieldOption> with the option name and <true|false> by the desired Boolean value. See Available Boolean Field Options for details.

A successful response (204 No Content) indicates that the field was successfully created in the target Coveo organization, if not already done.

Sample request

Creating several fields at once

POST https://platform.cloud.coveo.com/rest/organizations/mycoveocloudv2organizationg8tp8wu3/indexes/fields/batch/create HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

[
  {
    "name": "mysrc_productname",
    "description": "The name of the product that relates to the item (2017-11-20 ASmith)",
    "type": "STRING",
    "facet": true,
    "sort": true,
    "mergeWithLexicon": true
  },
  {
    "name": "mysrc_productid",
    "description": "The unique identifier of the product that relates to the item (2017-11-20 ASmith)",
    "type": "LONG_64"
  },
  {
    "name": "mysrc_productprice",
    "description": "The price of the product that relates to the item (2017-11-20 ASmith)",
    "type": "DOUBLE",
    "useCacheForNumericQuery": true,
    "useCacheForSort": true
  },
  {
    "name": "mysrc_productreleasedate",
    "description": "The official release date of the product that relates to the item (2017-11-20 ASmith)",
    "type": "DATE"
  }
]

Successful response - 204 No Content

{}