Get Parametric Values

Retrieves the unique values that occur in a particular field.

The Get Parametric Values API retrieves the unique values that occur in a particular field, which you can use to provide faceted search. For example, if you have a color parametric field, you can use this API to retrieve all the color values that occur in your documents. A common use for this information is to provide filters to end users.

For example:

Quick Start

﻿

The API returns a list of the values of the fields that you specify in the field_names parameter that exist in the indexes that you specify in the indexes parameter. The fields that you specify must be parametric or date type fields (see Index Field Types). If you do not specify the indexes parameter, the API uses the wiki_eng public text index.

You can use any parametric or date type field in a public or private text index. For a list of available fields in the public text indexes, see Public Text Indexes. In your private text indexes, there are a number of standard parametric fields available, depending on the flavor of the text index (see Index Flavors), and you can also add custom parametric fields when you create the text index. For more information about creating and using custom parametric fields, see the Create Text Index API, and the Use Parametric (Faceted) Search documentation.

When you specify multiple field names, by default, the response returns each field separately. This option allows you to create top level filters that specify the total number of documents available for values. You can also create a set of filters that depend on each other, by setting the nest_field_results parameter to true. In this case, the first field that you specify in the field_names array is the top level field, the second field that you specify is the first subfield, and so on. The API finds the values that occur in the first field, and returns values of the second field that occur in fields with this value. For example:

If any of the subfields are empty or missing from documents with a particular value in the top level field, the subfield is returned with the value null. The response still includes any further subfields, under the null entry.

Limit and Sort Results

By default, Get Parametric Values returns up to 100 possible values for each field, along with the number of documents that the value occurs in. The results are unsorted.

You can use the max_values parameter to restrict the number of field values to return. For example:

You can use the values that you retrieve with the Get Parametric Values API in a subsequent Query Text Index API call. For example, the following query returns the 24 documents that have the value ABBOT in the person_profession field, and prints that field in the results.

The date values return in ISO-8601 format. It can also return the values after upper end of range and before lower end of range. The sort value in the example call above ensures that the most recent dates return first.

You can use the date_period parameter to specify the most appropriate date grouping for your data. An hour is the smallest grouping, but you can also specify day, week, month, year, and century. For example:

You can adjust the date_period to provide the best grouping for your data. For example, if the data consists of tweets, an hour might be a suitable grouping. However, if your data contains historical information, the year or century options might be more suitable.

Use Get Parametric Values with a Query

By default, Get Parametric Values returns all the values available for a particular field in the text index (up to max_values). You can also add the text and field_text parameters to apply the Get Parametric Values request to the results of a particular query. These parameters accept the same values and syntax as the text and field_text parameters in the Query Text Index API.

For example, if you have a query filter that uses the parametric person_profession field, you can either run Get Parametric Values to return all possible professions in the wiki_eng text index, or you can add a query to return only person_profession values that occur in documents about painters:

You can also use field_text to add an additional field restriction. For example, the following query finds the values of the person_profession field that occur in documents that match the text painters, and which have the wikipedia_category value modern painters.

The Get Parametric Values API also allows you to set the min_score parameter for the query, to return only values for the specified field that match your query with a specified relevance score. This option means that you can restrict the list of values to ones that occur only in the most relevant documents that match your query.

If you set total_values to true when you also set text or field_text, the number of values that returns is the number of values in the set of documents that match your query, rather than the total number of values in the text index.

Parameters

The time interval to use for grouping together date values. This option only has an effect if one or more fields that you specify in field_names contain date values.
Default value: hour.

document_count

boolean

Set to true to show the number of documents that contain a parametric tag value.
Default value: true.

nest_field_results

boolean

Set to true to find sets of values that occur together in documents. The results are returned in a hierarchical structure, with the first field in the field_names array at the top, followed by the second, and so on.
Default value: false.

field_text

string

The fields that result documents must contain, and the conditions that these fields must meet for the documents to return as results. See Field Text Operators.

indexes

array<resource>

The text index to use to perform the parametric search.
Default value: [wiki_eng].

max_values

number

The maximum number of values to return for each matched field name. This parameter may be capped by your index flavour.
Default value: 100.

min_score

number

The minimum percentage relevance that results must have to the query to return.
Default value: 0.

Set to true to show the total number of values for each field (disregarding any max_values limit on the request).
Default value: false.

Enumeration Types

This API's parameters use the enumerations described below:

date_period
The time interval to use for grouping together date values. This option only has an effect if one or more fields that you specify in field_names contain date values.

century

Century
Group date values together by the century in which they occurred.

year

Year
Group date values together by the year in which they occurred.

month

Calendar month
Group date values together by the month in which they occurred.

week

Week
Group date values together in periods of one week.

day

Day
Group date values together in periods of one day.

hour

Hour
Group date values together in periods of one hour.

sort
The criteria to use for the result display order. By default, results are not sorted.

document_count

Number of matching documents (descending)
Order by the number of documents that contain the field, highest document count first. You can use this sort only when the document_count parameter is set to true.

reverse_document_count

Number of matching documents (ascending)
Order by the number of documents that contain the field, lowest document count first. You can use this sort only when the document_count parameter is set to true.

alphabetical

Alphabetical
Order alphabetically.

reverse_alphabetical

Reverse alphabetical
Order in reverse alphabetical order.

number_increasing

Numeric field value (lowest number first)
Order by the numeric value of the field, with the lowest number first. This option reverts to alphabetical order for non-numeric values.

number_decreasing

Numeric field value (highest number first)
Order by the numeric value of the field, with the highest number first. This option reverts to alphabetical order for non-numeric values.

date

Date value (most recent date first)
Order values by date, with the most recent date listed first. For this option, the fields that you specify in field_names must contain date values.

reverse_date

Date value (earliest date first)
Order values by date, with the earliest date is listed first. For this option, the fields that you specify in field_names must contain date values.

off

No sorting

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Haven OnDemand uses cookies to enhance and improve the experience it provides. By continuing to use this site or pressing Continue,
we will assume that you accept receiving all cookies. If you would like to change which cookies are set, you can change your settings.