# IRPCSearch.SearchObjects

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/SearchObjects/

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

Searches the vault for objects that match the given conditions.

- **Service:** [Search](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/index.md) `MFiles.IRPCSearch`
- **gRPC method:** `/MFiles.IRPCSearch/SearchObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/search-objects`
- **Request:** [`SearchObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md#request)
- **Response:** [`SearchObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/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

Results are filtered by the caller's permissions. See the service overview for the condition
model and for what a result contains.

**Order.** Without `sorting`, results are ranked by relevance (`SearchResultsItem.score`);
`SearchFlags.disable_relevancy_ranking` turns ranking off. `sorting` takes one rule; see
[SortRule](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SortRule/index.md) for the supported keys.

**Paging.** `page_requests` is not supported. To read a large result set in pages, sort by
object ID (sort key -102, ascending) and repeat the search with an extra
`STATUS_TYPE_OBJECT_ID` condition `CONDITION_TYPE_GREATER_THAN` the last object ID received,
until `has_more_results` is false. This works with database conditions only: object ID sorting
cannot be combined with a full-text (any-field) condition.

**Full-text search.** Add an `EXPRESSION_TYPE_ANY_FIELD` condition with `CONDITION_TYPE_CONTAINS`
and a text value. Its [FTSFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FTSFLAGS/index.md) must set `search_metadata`,
`search_filedata` or both; without either the call fails with "Invalid search condition.", and an
empty text fails with "The search request contained no text".

**Aino (semantic) search.** Setting `FTSFLAGS.search_aino` on the any-field condition runs the
search against the vault's enabled Aino index; `target` is then ignored. If the vault has no
enabled Aino index, the call fails with "An enabled Aino index must be present to make an Aino
Search." An Aino result carries the object ID, the title, one file ID, `score` and the matching
text passage in `chunk`. The other fields of `object` are not filled: Aino results do not carry
the class (`class_id` 0 does not mean the Document class) or the object version, and the file
version is reported as 1. Read the object with
[GetObjectVersionAndPropertiesOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectVersionAndPropertiesOfMultipleObjects/index.md)
before using those values. An Aino search that also has a `STATUS_TYPE_OBJECT_TYPE` condition
returns no results; filter by class or properties instead.

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

## Request: SearchObjectsRequest

> 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 |
|---|---|---|
| `call_importance` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | The importance level of this call. Typically `CALL_IMPORTANCE_NORMAL`. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
| `target` | [`SearchTarget`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchTarget/index.md) | The search index and search mode. Leave unset to use the vault's default index and `SEARCH_MODE_DEFAULT`. An unknown index name fails with "Target index is not available." |
| `target.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." |
| `target.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). |
| `target.search_master_storage` | `bool` | True to also search objects kept in Master Storage, where the vault supports it. |
| `target.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`. |
| `conditions[]` | 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. An empty array matches every object the caller can see, deleted objects included. No array or more than one array fails with "The parameter is incorrect." |
| `conditions[].value[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The conditions. All of them must match. |
| `conditions[].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). |
| `conditions[].value[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `conditions[].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`. |
| `options` | [`SearchFlags`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchFlags/index.md) | Search flags. Unset searches the latest versions of all object types as one relevance-ranked list. See [SearchFlags](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchFlags/index.md). |
| `options.all` | `bool` | All flags set, including any future flags. Do not use in searches. |
| `options.look_in_all_versions` | `bool` | Also match older versions; each object is returned once. Cannot be combined with `sorting`, and `GetObjectCountInSearch` rejects it. |
| `options.return_latest_visible_version` | `bool` | Return the latest visible version for each matching document. |
| `options.separately_search_in_each_object_type` | `bool` | Search each object type separately and merge the results. The `limit` then applies to each object type, and `pages_with_more_results` lists the object types whose results were cut. |
| `options.allow_quick_refresh_for_external_object_types` | `bool` | If a search with an external ID condition on an external object type finds nothing, refresh the object type from its external database and search again. |
| `options.disable_relevancy_ranking` | `bool` | Do not rank the results by relevance. |
| `options.separately_search_specific_object_types` | `bool` | Allows only specified object types to be searched separately. |
| `options.include_unmanaged_objects` | `bool` | Extends the search to include unmanaged objects. |
| `options.individual_limit_for_each_external_repository` | `bool` | Ensures that up to the specified maximum number of results are returned from each repository. |
| `page_requests[]` | repeated [`SearchResultsPageRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsPageRequest/index.md) | Not supported. Must be empty; otherwise the call fails with "Not implemented." |
| `page_requests[].object_type` | `int32` | The identifier of a search results group. |
| `page_requests[].page` | `int32` | The zero-based index of a page. |
| `page_requests[].options` | [`SRPREQUESTFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRPREQUESTFLAGS/index.md) | Search results page request flags. |
| `page_requests[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `page_requests[].options.unseen_page` | `bool` | If available, the page request is for an unseen page. |
| `page_requests[].options.ignore_original_conditions` | `bool` | If available, the original conditions are ignored. This can be used when including ObjIDs. Do not use with SRPREQUEST_UNSEENPAGE. |
| `page_requests[].options.seen_page` | `bool` | If available, the page request is for an already seen page. |
| `page_requests[].options.initial_page` | `bool` | If available, the page request is initial and for an unseen page. Do not use with SRPREQUEST_SEENPAGE. |
| `page_requests[].seen_objects[]` | repeated [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | An array of ObjIDs. If the SRPREQUEST_UNSEENPAGE flag is available, these are ObjIDs to exclude. If the SRPREQUEST_SEENPAGE flag is available, these are ObjIDs to include. |
| `page_requests[].seen_objects[].type` | `int32` | The object type ID, for example 0 for documents. In a lookup value, the value list ID (for a lookup to objects, the object type ID). |
| `page_requests[].seen_objects[].item_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | The ID of the object within its type, in `item_id.internal_id`. |
| `limit` | `uint32` | The maximum number of results. 0 means no limit: the server does not apply a default, only a maximum that the vault administrator may have configured. With `separately_search_in_each_object_type` the limit applies to each object type, and the values 200 and 500 select the server default of 50 results per object type. With `sorting` and 0, at most 20,000 results (a vault setting) are sorted. |
| `timeout_in_seconds` | `uint32` | The search timeout in seconds. 0 means no timeout. A maximum configured for the vault caps larger values and replaces 0. A search that times out fails. |
| `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. |
| `sorting` | [`SearchResultsSorting`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsSorting/index.md) | How to sort the results. Unset sorts by relevance. At most one rule; see [SearchResultsSorting](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsSorting/index.md). |
| `sorting.rules` | [`SortRuleValueArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SortRuleValueArray/index.md) | The sort rule. Exactly one rule is supported; more than one cannot be sorted. |
| `sorting.rules.values[]` | repeated [`SortRule`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SortRule/index.md) | Sort rules. The first rule has the highest presedence meaning that it is the primary sort rule. |
| `sorting.options` | [`SortFlags`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SortFlags/index.md) | Sort flags. Set `allow_resorting_to_default_sort` to get relevance order instead of an error when the rule cannot be applied. |
| `sorting.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `sorting.options.allow_resorting_to_default_sort` | `bool` | Allows resorting to default sorting if the specified sorting is not supported. If this flag is not present, an unsupported sort request causes an error. |

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

## Response: SearchObjectsResponse

> 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 |
|---|---|---|
| `results[]` | repeated [`SearchResultsItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchResultsItem/index.md) | The matching objects, at most `limit`. Each item has the object and version information but not the property values. |
| `results[].object` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | The object and the found version: object ID, version, title, class, files and status. Property values are not included. |
| `results[].object.version_info` | [`ObjectVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersion/index.md) | Object Version information. |
| `results[].object.object_info` | [`ObjectLevelInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectLevelInfo/index.md) | Object-level information. |
| `results[].score` | `int32` | The relevance score of the result. Higher is more relevant. |
| `results[].chunk` | `string` | For an Aino search, the passage of text that matched. Empty for other searches. |
| `has_more_results` | `bool` | True if more objects match than were returned. |
| `pages_with_more_results[]` | repeated `int32` | With `separately_search_in_each_object_type`, the object type IDs whose results were cut by `limit`. Otherwise empty. |
| `search_execution_info` | [`SearchOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchOutputInfo/index.md) | Timing information for diagnostics. |
| `search_execution_info.processing_time_at_engine_in_milliseconds` | `int32` | The processing time at the search engine, in milliseconds. -1 if not known. |
| `search_execution_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_execution_info.processing_time_at_mfserver_in_milliseconds` | `int32` | The total processing time at MFServer, in milliseconds. -1 if not known. |
| `search_execution_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. |
| `options` | [`SEARCHSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SEARCHSTATUSFLAGS/index.md) | Search status flags, for example `resorted_to_default_sort` when the requested sorting was replaced by relevance order. |
| `options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `options.multiphase_object_type_search_needed` | `bool` | Multi-phase OT search is needed. |
| `options.wildcard_expansion_limit_exceeded` | `bool` | Wildcard expansion limit has been exceeded (but some results has been returned anyway). |
| `options.may_contain_stale_data` | `bool` | Data returned by search may be out of date. |
| `options.resorted_to_default_sort` | `bool` | Requested sorting is not supported and result set was established using the default sorting (relevance). |
| `options.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. |
| `options.sorted_by_engine` | `bool` | Data returned by search was sorted by the engine (Global Sorting). |

<a id="related"></a>

## Related methods

- [IRPCObjectOperations.GetObjectVersionAndPropertiesOfMultipleObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetObjectVersionAndPropertiesOfMultipleObjects/index.md): Gets the version information and the property values of several objects in one call. The preferred way to read objects.