IRPCSearch.SearchObjects
Vault API / core read session or assertion idempotent returns metadata structure version
Searches the vault for objects that match the given conditions.
| Service | Search MFiles.IRPCSearch |
|---|---|
| gRPC method | /MFiles.IRPCSearch/SearchObjects |
| HTTP (mf-http-grpc) | POST /grpc/v1/search-objects |
| Request | SearchObjectsRequest |
| Response | SearchObjectsResponse |
| 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) |
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 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 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
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.
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 | 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 | 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 | Whether to prefer, require or avoid the full-text search engine. See SearchMode.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 | 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 | The conditions. All of them must match. |
conditions[].value[].expression | Expression | 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 | The comparison operator. |
conditions[].value[].value | TypedValue | 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 | Search flags. Unset searches the latest versions of all object types as one relevance-ranked list. See SearchFlags. |
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 | 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 | 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 | 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 | 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 | If set, specifies the additional facet search filter. |
facet_filter.value | string | String. |
sorting | SearchResultsSorting | How to sort the results. Unset sorts by relevance. At most one rule; see SearchResultsSorting. |
sorting.rules | SortRuleValueArray | The sort rule. Exactly one rule is supported; more than one cannot be sorted. |
sorting.rules.values[] | repeated SortRule | Sort rules. The first rule has the highest presedence meaning that it is the primary sort rule. |
sorting.options | SortFlags | 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. |
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 | The matching objects, at most limit. Each item has the object and version information but not the property values. |
results[].object | ObjectVersionEx | The object and the found version: object ID, version, title, class, files and status. Property values are not included. |
results[].object.version_info | ObjectVersion | Object Version information. |
results[].object.object_info | ObjectLevelInfo | 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 | 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 | 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). |
Related methods
- IRPCObjectOperations.GetObjectVersionAndPropertiesOfMultipleObjects -- Gets the version information and the property values of several objects in one call. The preferred way to read objects.