Metadata queries

Metadata queries retrieve information about the fields, such as name, data type, and options (enumerated values or range-values in a scale). Issue a metadata query with a fields element.

query getFields{
    fields(…)
}

Filtering fields

Use filters to narrow the range of results.

ids — returns info on the fields whose IDs are specified.
dataType — finds fields of a specific data type, where the types are: DATE, DATETIME, TIME, EMAIL, ENUM, STRING, UNIT, URL, INT, FLOAT.
q — finds fields whose names contain the specified string.
filterable — finds fields that are filterable in Query API.

Note: The ids option has priority over dataType and q; they are ignored when ids is included.

Note: Pagination is not supported when ids are provided.

Example: Metadata query

This example retrieves the metadata for the field whose ID is e_bp_wm_client_aum_alt. Notice the filter also include q and dataType filter options, but those are ignored because ids is included.

Example: Retrieve metadata for specified fields

query getFields{
fields(
    ids:["e_bp_wm_client_aum_alt"],    # Get metadata for these specific fields
    q:"scale"           # Filter those fields that have the string as part of the name
    dataTypes:[ENUM]    # Filter fields for the given type
    after:null          # Cursor as starting point for the page
    first:200           # Page size
  ){
    pageInfo{ 
      endCursor         # Use as "after" parameter for next page
      hasNextPage       # Indicates the query has more pages that can be retrieved
    }
    totalCount          # Total number of element that matched the filter
    nodes{
      id                # Field identifier
      name              # Field name
      dataType          # DATE, DATETIME, TIME, EMAIL, ENUM, STRING, UNIT, URL, INT, FLOAT
      valueType         # Structure of the values for this field, SINGLE_VALUED, MULTI_VALUED, RANKING, NO_VALUE 
      filterable        # True when this field can be used as part of a filter
      ... on EnumField {
        options{        # Enumerated list of options. Null when there are no options
          id            # Option identifier. Use this ID filter by options
          name          # Name for the option
        }
      }
    }
  } 
}

Sample response

{
  "data": {
    "fields": {
      "pageInfo": {
        "endCursor": null,
        "hasNextPage": false
      },
      "totalCount": 1,
      "nodes": [
        {
          "id": "e_bp_wm_client_aum_alt",
          "name": "Assets Under Management",
          "dataType": "ENUM",
          "valueType": "SINGLE_VALUED",
          "filterable": true,
          "options": [
            {
              "id": "1",
              "name": "< 100K"
            },
            {
              "id": "2",
              "name": "100K - 500K"
            },
            {
              "id": "3",
              "name": "500K - 1M"
            },
            {
              "id": "4",
              "name": "1 - 10M"
            },
            {
              "id": "5",
              "name": "10 - 100M"
            },
            {
              "id": "6",
              "name": "100M+"
            }
          ]
        }
      ]
    }
  },
  "errors": null,
  "_links": null,
  "_allowed": [
    "POST"
  ]
}

Best practice: multiple fields

When the query has multiple fields, do not ask the field’s metadata inline with the fieldData. The metadata is the same for all fields and asking it on each fieldData, returns the same metadata for each returned record, which is a waste of resources and the query will be penalized with more cost.

Bad practice

Code showing metadata request inline as part of the query

Best practice

Instead, include another query in the same request, and only ask for the metadata for the needed fields.

Code showing metadata request as a separate query