Creating Fields With the API

This is for:

Developer System Administrator
In this article

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

  • In general, a given field should have a single purpose (although concatenating many 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.

You can also perform this action from the Coveo Administration Console (see Manage fields - Add a new field).

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:

In the Authorization HTTP header:

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.

    Valid field names

    "productname"
"productname1"
"product_name"
"product_name1"
"p__r0ductn4m3_"

    Invalid field names

    "Productname"
"productName"
"1productname"
"_productname"
"@productname"
"product name"
"productname "

    You can’t change the name of a field once it has been created.

  • Replace <MyFieldDescription> with a string that clearly explains the purpose of the field.

    Although doing so is optional, you should generally provide a value for the description property. A field description should typically include information such as the intended purpose of that field, as well as who created it and when.

  • 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 (see Allowed Metadata Types).

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

    If you want to create a Boolean field, use the STRING type.

  • If you’re creating a DATE type field and you want to ensure that the field only recognizes a specific, non-standard date and time string format:

    • Replace <MyDateFormat> with the desired pattern.

    Otherwise, you don’t need to include the dateFormat property in your request body.

    By default, a DATE type field recognizes several standard date and time string formats (see Allowed Metadata Types - About the Date Field Type).

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

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

{}