Creating Fields

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 Cloud indexing pipeline processes an incoming item (see Managing the Mapping Configuration of a Source).

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

    Rather than creating a field named product in your Coveo Cloud 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 (e.g., 1234-abcd|My Product Name), you should consider creating a distinct field for each of those metadata (e.g., 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 (e.g., mysrc_productid, mysrc_productname).

Use the Create a batch of fields operation to create one or more fields in a Coveo Cloud organization.

You can also perform this action from the Coveo Cloud administration console (see Adding and Managing 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 cannot 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 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 bests corresponds to the data type you intend to populate the field with (see Allowed Metadata Types ).

    You cannot 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 are 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 do not 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 - Understanding the Date Field Type).

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

    Moreover, it is important to keep in mind that fields are index-wide containers. This implies that if you specify a custom dateFormat for a field that is targeted by the mappings of several distinct non-Push sources, chances are that the Coveo Cloud 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 Cloud organization.

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

{}