# IRPCSearch.GetFacetValues

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFacetValues/

Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`

Retrieves the facet values for the documents that satisfy the specified search conditions.

- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/GetFacetValues`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-facet-values`
- **Request:** [`GetFacetValuesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFacetValues/index.md#request)
- **Response:** [`GetFacetValuesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/GetFacetValues/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

For search UIs that show facets (refiners) next to full-text search results. Facets are computed
only when the vault's search index supports them (not with a dtSearch index) and the search has
exactly one full-text (any-field) condition. Otherwise the call succeeds with empty `data`. The
`data` string uses an
internal format that the M-Files clients read; it is not described here.

<a id="request"></a>

## Request: GetFacetValuesRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `search_options` | [`SearchTarget`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchTarget/index.md) | Search options. |
| `search_options.index` | `string` | The name of the search index to use. Empty uses the vault's default index. An unknown name fails with "Target index is not available." |
| `search_options.mode` | [`SearchMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md) | Whether to prefer, require or avoid the full-text search engine. See [SearchMode](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchMode/index.md). Values: `SEARCH_MODE_DEFAULT` (0), `SEARCH_MODE_FAVOR_FULL_TEXT_SEARCH` (1), `SEARCH_MODE_REQUIRE_FULL_TEXT_SEARCH` (2), `SEARCH_MODE_REQUIRE_DATABASE_SEARCH` (3). |
| `search_options.search_master_storage` | `bool` | True to also search objects kept in Master Storage, where the vault supports it. |
| `search_options.continuation_token` | `string` | Continuation token for paging results from Master Storage. `SearchObjects` does not support it and fails with "Continuation token is not supported." when it is set together with `search_master_storage`. |
| `search_condition_arrays[]` | repeated [`SearchConditionArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchConditionArray/index.md) | Exactly one condition array; all of its conditions must match. No array or more than one array fails with "Invalid search condition." |
| `search_condition_arrays[].value[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The conditions. All of them must match. |
| `search_condition_arrays[].value[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `search_condition_arrays[].value[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `search_condition_arrays[].value[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `facets_requested[]` | repeated [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The facets to compute, as expressions; for example an `EXPRESSION_TYPE_PROPERTY_VALUE` expression for property 100 (Class). |
| `facets_requested[].type` | [`ExpressionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExpressionType/index.md) | The kind of expression. Must match the member set in `data`. Values: `EXPRESSION_TYPE_UNINITIALIZED` (0), `EXPRESSION_TYPE_PROPERTY_VALUE` (1), `EXPRESSION_TYPE_ID_SEGMENT` (2), `EXPRESSION_TYPE_STATUS_VALUE` (3), `EXPRESSION_TYPE_FILE_VALUE` (4), `EXPRESSION_TYPE_TYPED_VALUE` (5), `EXPRESSION_TYPE_ANY_FIELD` (6), `EXPRESSION_TYPE_PERMISSIONS` (7). |
| `facets_requested[].data` | [`ExpressionUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md) | The expression data. Set the member that matches `type`. |
| `facets_requested[].data.property_value` | [`ExpressionUnion.PropertyValueData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md#t-PropertyValueData) (oneof data) | Expression for property values. |
| `facets_requested[].data.id_segment` | [`ExpressionUnion.IdSegmentData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md#t-IdSegmentData) (oneof data) | Expression for document ID segments. |
| `facets_requested[].data.status_value` | [`ExpressionUnion.StatusValueData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md#t-StatusValueData) (oneof data) | Expression for status values such as Document ID or CheckedOutToUser. |
| `facets_requested[].data.file_value` | [`ExpressionUnion.FileValueData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md#t-FileValueData) (oneof data) | Expression for file values such as file size. |
| `facets_requested[].data.typed_value` | [`ExpressionUnion.TypedValueData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md#t-TypedValueData) (oneof data) | Expression for values of specific data type. Lookup-typed values also specify the value list. |
| `facets_requested[].data.any_field` | [`ExpressionUnion.AnyFieldData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md#t-AnyFieldData) (oneof data) | Expression for values of any field (any property, file name etc.). |
| `facets_requested[].data.permissions` | [`ExpressionUnion.PermissionsData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md#t-PermissionsData) (oneof data) | Expression for permissions (ACL). |
| `facets_requested[].indirection_levels[]` | repeated [`IndirectionLevel`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.IndirectionLevel/index.md) | The lookups to follow before evaluating the expression, from the searched object outwards. Empty evaluates the expression on the object itself. |
| `facets_requested[].indirection_levels[].type` | `bool` | True if `id` is a property definition ID; false if it is an object type ID. An object type level follows a reference to an object of that type through any property. |
| `facets_requested[].indirection_levels[].id` | `int32` | The property definition ID or object type ID to follow. |
| `max_facet_values_count` | `uint32` | The maximum number of facet values returned for each facet. Use 0 to retrieve all facet values. |
| `facetsearchflags` | [`FACETSEARCHFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FACETSEARCHFLAGS/index.md) | Facet search flags. Ignored if bFacetMode is false. |
| `facetsearchflags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `facetsearchflags.enabled` | `bool` | Facet search is enabled. |
| `facetsearchflags.ignore_search_permissions` | `bool` | No ACL check on facet search. |
| `facetsearchflags.ignore_group_permissions` | `bool` | No ACL check on facet groups. |
| `facetsearchflags.ignore_value_permissions` | `bool` | No ACL check on individual facet values. |
| `facetsearchflags.sort_facets` | `bool` | Sort facet values in descending occurrence order within each facet group. |
| `facetsearchflags.ascending_order` | `bool` | If SortFacetValues is present, sort facet values in ascending occurrence order within each facet group. |
| `facet_filter` | [`StringValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringValue/index.md) | If set, specifies the additional facet search filter. |
| `facet_filter.value` | `string` | String. |

<a id="response"></a>

## Response: GetFacetValuesResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `data` | `string` | Receives the facet values as string data. Use CData_FacetValues to inspect the data. |
| `psearchstatusflags` | [`SEARCHSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SEARCHSTATUSFLAGS/index.md) | Receives search status flags. |
| `psearchstatusflags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `psearchstatusflags.multiphase_object_type_search_needed` | `bool` | Multi-phase OT search is needed. |
| `psearchstatusflags.wildcard_expansion_limit_exceeded` | `bool` | Wildcard expansion limit has been exceeded (but some results has been returned anyway). |
| `psearchstatusflags.may_contain_stale_data` | `bool` | Data returned by search may be out of date. |
| `psearchstatusflags.resorted_to_default_sort` | `bool` | Requested sorting is not supported and result set was established using the default sorting (relevance). |
| `psearchstatusflags.resorted_to_default_sort_too_many_results` | `bool` | Requested sorting is not supported and result set was established using the default sorting (relevance) because there are too many matching results for sorting. |
| `psearchstatusflags.sorted_by_engine` | `bool` | Data returned by search was sorted by the engine (Global Sorting). |
| `search_output_info` | [`SearchOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchOutputInfo/index.md) | Additional information about the completed search operation. |
| `search_output_info.processing_time_at_engine_in_milliseconds` | `int32` | The processing time at the search engine, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_engine_from_mfserver_in_milliseconds` | `int32` | The processing time at the search engine, including network roundtrip from MFServer, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_mfserver_in_milliseconds` | `int32` | The total processing time at MFServer, in milliseconds. -1 if not known. |
| `search_output_info.processing_time_at_mfserver_from_client_in_milliseconds` | `int32` | The total processing time at MFServer, including network roundtrip from the client, in milliseconds. -1 if not known. |