Method: projects.locations.documents.search

string

Required. The parent, which owns this collection of documents. Format: projects/{projectNumber}/locations/{location}. It takes the form projects/{project}/locations/{location}.

{
  "query": string,
  "isNlQuery": boolean,
  "customPropertyFilter": string,
  "timeFilters": [
    {
      object (TimeFilter)
    }
  ],
  "documentSchemaNames": [
    string
  ],
  "propertyFilter": [
    {
      object (PropertyFilter)
    }
  ],
  "fileTypeFilter": {
    object (FileTypeFilter)
  },
  "folderNameFilter": string,
  "documentNameFilter": [
    string
  ],
  "queryContext": [
    string
  ],
  "documentCreatorFilter": [
    string
  ],
  "customWeightsMetadata": {
    object (CustomWeightsMetadata)
  }
}

string

The query string that matches against the full text of the document and the searchable properties.

The query partially supports Google AIP style syntax. Specifically, the query supports literals, logical operators, negation operators, comparison operators, and functions.

Literals: A bare literal value (examples: "42", "Hugo") is a value to be matched against. It searches over the full text of the document and the searchable properties.

Logical operators: "AND", "and", "OR", and "or" are binary logical operators (example: "engineer OR developer").

Negation operators: "NOT" and "!" are negation operators (example: "NOT software").

Comparison operators: support the binary comparison operators =, !=, <, >, <= and >= for string, numeric, enum, boolean. Also support like operator ~~ for string. It provides semantic search functionality by parsing, stemming and doing synonyms expansion against the input query.

To specify a property in the query, the left hand side expression in the comparison must be the property id including the parent. The right hand side must be literals. For example: ""projects/123/locations/us".property_a < 1" matches results whose "property_a" is less than 1 in project 123 and us location. The literals and comparison expression can be connected in a single query (example: "software engineer "projects/123/locations/us".salary > 100").

Functions: supported functions are LOWER([propertyName]) to perform a case insensitive match and EMPTY([propertyName]) to filter on the existence of a key.

Support nested expressions connected using parenthesis and logical operators. The default logical operators is AND if there is no operators between expressions.

The query can be used with other filters e.g. timeFilters and folderNameFilter. They are connected with AND operator under the hood.

The maximum number of allowed characters is 255.

boolean

Experimental, do not use. If the query is a natural language question. False by default. If true, then the question-answering feature will be used instead of search, and resultCount in SearchDocumentsRequest must be set. In addition, all other input fields related to search (pagination, histograms, etc.) will be ignored.

string

This filter specifies a structured syntax to match against the [PropertyDefinition].[isFilterable][] marked as true. The syntax for this expression is a subset of SQL syntax.

Supported operators are: =, !=, <, <=, >, and >= where the left of the operator is a property name and the right of the operator is a number or a quoted string. You must escape backslash (\) and quote (") characters. Supported functions are LOWER([propertyName]) to perform a case insensitive match and EMPTY([propertyName]) to filter on the existence of a key.

Boolean expressions (AND/OR/NOT) are supported up to 3 levels of nesting (for example, "((A AND B AND C) OR NOT D) AND E"), a maximum of 100 comparisons or functions are allowed in the expression. The expression must be < 6000 bytes in length.

Sample Query: (LOWER(driving_license)="class \"a\"" OR EMPTY(driving_license)) AND driving_years > 10

object (TimeFilter)

Documents created/updated within a range specified by this filter are searched against.

string

This filter specifies the exact document schema Document.document_schema_name of the documents to search against.

If a value isn't specified, documents within the search results are associated with any schema. If multiple values are specified, documents within the search results may be associated with any of the specified schemas.

At most 20 document schema names are allowed.

object (PropertyFilter)

This filter specifies a structured syntax to match against the PropertyDefinition.is_filterable marked as true. The relationship between the PropertyFilters is OR.

object (FileTypeFilter)

This filter specifies the types of files to return: ALL, FOLDER, or FILE. If FOLDER or FILE is specified, then only either folders or files will be returned, respectively. If ALL is specified, both folders and files will be returned.

If no value is specified, ALL files will be returned.

string

Search all the documents under this specified folder. Format: projects/{projectNumber}/locations/{location}/documents/{documentId}.

string

Search the documents in the list. Format: projects/{projectNumber}/locations/{location}/documents/{documentId}.

string

For custom synonyms. Customers provide the synonyms based on context. One customer can provide multiple set of synonyms based on different context. The search query will be expanded based on the custom synonyms of the query context set. By default, no custom synonyms wll be applied if no query context is provided. It is not supported for CMEK compliant deployment.

string

The exact creator(s) of the documents to search against.

If a value isn't specified, documents within the search results are associated with any creator. If multiple values are specified, documents within the search results may be associated with any of the specified creators.

object (CustomWeightsMetadata)

To support the custom weighting across document schemas, customers need to provide the properties to be used to boost the ranking in the search request. For a search query with CustomWeightsMetadata specified, only the RetrievalImportance for the properties in the CustomWeightsMetadata will be honored.

{
  "timeRange": {
    object (Interval)
  },
  "timeField": enum (TimeField)
}

object (Interval)

enum (TimeField)

Specifies which time field to filter documents on.

Defaults to [TimeField.UPLOAD_TIME][].

{
  "startTime": string,
  "endTime": string
}

string (Timestamp format)

Optional. Inclusive start of the interval.

If specified, a timestamp matching this interval will have to be the same or after the start.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

string (Timestamp format)

Optional. Exclusive end of the interval.

If specified, a timestamp matching this interval will have to be before the end.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

{
  "documentSchemaName": string,
  "condition": string
}

string

The Document schema name Document.document_schema_name. Format: projects/{projectNumber}/locations/{location}/documentSchemas/{document_schema_id}.

string

The filter condition. The syntax for this expression is a subset of SQL syntax.

Supported operators are: =, !=, <, <=, >, >=, and ~~ where the left of the operator is a property name and the right of the operator is a number or a quoted string. You must escape backslash (\) and quote (") characters.

~~ is the LIKE operator. The right of the operator must be a string. The only supported property data type for LIKE is textValues. It provides semantic search functionality by parsing, stemming and doing synonyms expansion against the input query. It matches if the property contains semantic similar content to the query. It is not regex matching or wildcard matching. For example, "property.company ~~ "google"" will match records whose property property.compnay have values like "Google Inc.", "Google LLC" or "Google Company".

Supported functions are LOWER([propertyName]) to perform a case insensitive match and EMPTY([propertyName]) to filter on the existence of a key.

Boolean expressions (AND/OR/NOT) are supported up to 3 levels of nesting (for example, "((A AND B AND C) OR NOT D) AND E"), a maximum of 100 comparisons or functions are allowed in the expression. The expression must be < 6000 bytes in length.

Only properties that are marked filterable are allowed (PropertyDefinition.is_filterable). Property names do not need to be prefixed by the document schema id (as is the case with histograms), however property names will need to be prefixed by its parent hierarchy, if any. For example: top_property_name.sub_property_name.

Sample Query: (LOWER(driving_license)="class \"a\"" OR EMPTY(driving_license)) AND driving_years > 10

CMEK compliant deployment only supports:

• Operators: =, <, <=, >, and >=.
• Boolean expressions: AND and OR.

{
  "fileType": enum (FileType)
}

enum (FileType)

The type of files to return.

{
  "weightedSchemaProperties": [
    {
      object (WeightedSchemaProperty)
    }
  ]
}

object (WeightedSchemaProperty)

List of schema and property name. Allows a maximum of 10 schemas to be specified for relevance boosting.

{
  "documentSchemaName": string,
  "propertyNames": [
    string
  ]
}

string

The document schema name.

string

The property definition names in the schema.

{
  "histogramQuery": string,
  "requirePreciseResultSize": boolean,
  "filters": {
    object (HistogramQueryPropertyNameFilter)
  }
}

string

An expression specifies a histogram request against matching documents for searches.

See SearchDocumentsRequest.histogram_queries for details about syntax.

boolean

Controls if the histogram query requires the return of a precise count. Enable this flag may adversely impact performance.

Defaults to true.

object (HistogramQueryPropertyNameFilter)

Optional. Filter the result of histogram query by the property names. It only works with histogram query count('FilterableProperties'). It is an optional. It will perform histogram on all the property names for all the document schemas. Setting this field will have a better performance.

{
  "documentSchemas": [
    string
  ],
  "propertyNames": [
    string
  ],
  "yAxis": enum (HistogramYAxis)
}

string

This filter specifies the exact document schema(s) Document.document_schema_name to run histogram query against. It is optional. It will perform histogram for property names for all the document schemas if it is not set.

At most 10 document schema names are allowed. Format: projects/{projectNumber}/locations/{location}/documentSchemas/{document_schema_id}.

string

It is optional. It will perform histogram for all the property names if it is not set. The properties need to be defined with the isFilterable flag set to true and the name of the property should be in the format: "schemaId.propertyName". The property needs to be defined in the schema. Example: the schema id is abc. Then the name of property for property MORTGAGE_TYPE will be "abc.MORTGAGE_TYPE".

enum (HistogramYAxis)

By default, the yAxis is HISTOGRAM_YAXIS_DOCUMENT if this field is not set.

{
  "document": {
    object (Document)
  },
  "searchTextSnippet": string,
  "qaResult": {
    object (QAResult)
  }
}

object (Document)

Document that matches the specified SearchDocumentsRequest. This document only contains indexed metadata information.

string

Contains snippets of text from the document full raw text that most closely match a search query's keywords, if available. All HTML tags in the original fields are stripped when returned in this field, and matching query keywords are enclosed in HTML bold tags.

If the question-answering feature is enabled, this field will instead contain a snippet that answers the user's natural-language query. No HTML bold tags will be present, and highlights in the answer snippet can be found in QAResult.highlights.

object (QAResult)

Experimental. Additional result info if the question-answering feature is enabled.

{
  "highlights": [
    {
      object (Highlight)
    }
  ],
  "confidenceScore": number
}

object (Highlight)

Highlighted sections in the snippet.

number

The calibrated confidence score for this document, in the range [0., 1.]. This represents the confidence level for whether the returned document and snippet answers the user's query.

{
  "startIndex": integer,
  "endIndex": integer
}

integer

Start index of the highlight.

integer

End index of the highlight, exclusive.

{
  "histogramQuery": string,
  "histogram": {
    string: string,
    ...
  }
}

string

Requested histogram expression.

map (key: string, value: string (int64 format))

A map from the values of the facet associated with distinct values to the number of matching entries with corresponding value.

The key format is:

• (for string histogram) string values stored in the field.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.