Search

View as Markdown

There are no folders to walk in a vault. To find objects you describe them with conditions and call SearchObjects (or GetObjectCountInSearch to count them). A search takes one array of conditions that must all match, returns only objects the caller may see (for users who may see deleted objects, also deleted ones unless a condition excludes them), and returns no property values. The methods are in the IRPCSearch reference; the search guide builds a complete search step by step.

The condition model

SearchObjectsRequest
  conditions: [ SearchConditionArray ]       exactly one array
    value: [ SearchCondition, ... ]          all conditions must match (AND)
      expression  what to test     property 100 | status "is deleted" | any field (full text)
      type        how to compare   CONDITION_TYPE_EQUAL | _CONTAINS | _GREATER_THAN | ...
      value       compare to what  a TypedValue, like a property value

Expression kinds (ExpressionType):

Expression Set Use for
EXPRESSION_TYPE_PROPERTY_VALUE data.property_value.property_def a property: class, title, dates, lookups
EXPRESSION_TYPE_STATUS_VALUE data.status_value.type (StatusType) object type, ID, deleted, checked out
EXPRESSION_TYPE_ANY_FIELD data.any_field.options (FTSFLAGS) full-text search, Aino search
EXPRESSION_TYPE_TYPED_VALUE data.typed_value any lookup to a value list, whichever property holds it
EXPRESSION_TYPE_FILE_VALUE data.file_value.type file name, size, has files

An expression can also follow lookups to other objects ("documents whose project's customer is X") with Expression.indirection_levels; see IndirectionLevel.

Conditions you need most

Shown in protobuf text format. IDs above 1000 are from the Sample Vault.

# Object type is Document (0): a lookup to the object type.
expression { type: EXPRESSION_TYPE_STATUS_VALUE
             data { status_value { type: STATUS_TYPE_OBJECT_TYPE } } }
type: CONDITION_TYPE_EQUAL
value { type: DATATYPE_LOOKUP
        data { lookup { value_list_item_info { obj_id { item_id { internal_id: 0 } } } } } }

# Not deleted. Add this to almost every search (see "What comes back").
expression { type: EXPRESSION_TYPE_STATUS_VALUE
             data { status_value { type: STATUS_TYPE_IS_DELETED } } }
type: CONDITION_TYPE_EQUAL
value { type: DATATYPE_BOOLEAN data { boolean: false } }

# Class (property 100) is 2, "Purchase Invoice".
expression { type: EXPRESSION_TYPE_PROPERTY_VALUE
             data { property_value { property_def: 100 } } }
type: CONDITION_TYPE_EQUAL
value { type: DATATYPE_LOOKUP
        data { lookup { value_list_item_info {
          obj_id { type: 1 item_id { internal_id: 2 } } } } } }

# Customer (property 1079, a multi-select lookup) includes customer 141. A single lookup
# value matches objects whose multi-select value contains it.
expression { type: EXPRESSION_TYPE_PROPERTY_VALUE
             data { property_value { property_def: 1079 } } }
type: CONDITION_TYPE_EQUAL
value { type: DATATYPE_LOOKUP
        data { lookup { value_list_item_info {
          obj_id { type: 136 item_id { internal_id: 141 } } } } } }

# Title (property 0) contains "ups". Text comparisons ignore case.
expression { type: EXPRESSION_TYPE_PROPERTY_VALUE
             data { property_value { property_def: 0 } } }
type: CONDITION_TYPE_CONTAINS
value { type: DATATYPE_TEXT data { text: "ups" } }

# Last modified (property 21) on or after 2012-01-01T00:00:00Z.
expression { type: EXPRESSION_TYPE_PROPERTY_VALUE
             data { property_value { property_def: 21 } } }
type: CONDITION_TYPE_GREATER_THAN_OR_EQUAL
value { type: DATATYPE_TIMESTAMP data { timestamp { seconds: 1325376000 } } }

# One object: type 136, ID 142. STATUS_TYPE_OBJECT_ID alone would also match document 142.
expression { type: EXPRESSION_TYPE_STATUS_VALUE
             data { status_value { type: STATUS_TYPE_OBJECT_TYPE_AND_ID } } }
type: CONDITION_TYPE_EQUAL
value { type: DATATYPE_LOOKUP
        data { lookup { value_list_item_info {
          obj_id { type: 136 item_id { internal_id: 142 } } } } } }

# Full text in metadata and file contents.
expression { type: EXPRESSION_TYPE_ANY_FIELD
             data { any_field { options { search_metadata: true search_filedata: true } } } }
type: CONDITION_TYPE_CONTAINS
value { type: DATATYPE_TEXT data { text: "invoice" } }

A full-text condition must set search_metadata, search_filedata or both; with neither, the call fails with "Invalid search condition." Setting FTSFLAGS.search_aino instead runs an Aino (semantic) search, which needs an enabled Aino index in the vault: without one the call fails with "An enabled Aino index must be present to make an Aino Search." Aino results carry the matching text passage in SearchResultsItem.chunk, but not the class or the object version, and their file version is reported as 1: read the objects before using those values (see SearchObjects).

What comes back

Limits, timeouts, sorting and paging

Errors

Search errors come back with gRPC status UNKNOWN and the M-Files message as the status details, for example "Invalid search condition." or "The parameter is incorrect." (Errors shows how to read the error code). A condition built with the wrong ID space usually does not fail: it just finds nothing, or finds the wrong objects. When a search returns nothing, check the IDs against the ID spaces first.