--- title: "POST /v1/{+parent}/documents:search" method: POST path: "/v1/{+parent}/documents:search" tags: ["projects"] --- # POST /v1/{+parent}/documents:search `POST /v1/{+parent}/documents:search` Searches for documents using provided SearchDocumentsRequest. This call only returns documents that the caller has permission to search against. ## Path parameters - `parent` string, required ## Request body - GoogleCloudContentwarehouseV1SearchDocumentsRequest — Request message for DocumentService.SearchDocuments. - `requireTotalSize` boolean — Controls if the search document request requires the return of a total size of matched documents. See SearchDocumentsResponse.total_size. Enabling this flag may adversely impact performance. Hint: If this is used with pagination, set this flag on the initial query but set this to false on subsequent page calls (keep the total count locally). Defaults to false. - `orderBy` string — The criteria determining how search results are sorted. For non-empty query, default is `"relevance desc"`. For empty query, default is `"upload_date desc"`. Supported options are: * `"relevance desc"`: By relevance descending, as determined by the API algorithms. * `"upload_date desc"`: By upload date descending. * `"upload_date"`: By upload date ascending. * `"update_date desc"`: By last updated date descending. * `"update_date"`: By last updated date ascending. * `"retrieval_importance desc"`: By retrieval importance of properties descending. This feature is still under development, please do not use unless otherwise instructed to do so. - `requestMetadata` GoogleCloudContentwarehouseV1RequestMetadata — Meta information is used to improve the performance of the service. - `userInfo` GoogleCloudContentwarehouseV1UserInfo — The user information. - `id` string — A unique user identification string, as determined by the client. The maximum number of allowed characters is 255. Allowed characters include numbers 0 to 9, uppercase and lowercase letters, and restricted special symbols (:, @, +, -, _, ~) The format is "user:xxxx@example.com"; - `groupIds` string[] — The unique group identifications which the user is belong to. The format is "group:yyyy@example.com"; - `totalResultSize` 'TOTAL_RESULT_SIZE_UNSPECIFIED' | 'ESTIMATED_SIZE' | 'ACTUAL_SIZE' — Controls if the search document request requires the return of a total size of matched documents. See SearchDocumentsResponse.total_size. - `pageToken` string — The token specifying the current offset within search results. See SearchDocumentsResponse.next_page_token for an explanation of how to obtain the next set of query results. - `qaSizeLimit` integer — Experimental, do not use. The limit on the number of documents returned for the question-answering feature. To enable the question-answering feature, set [DocumentQuery].is_nl_query to true. - `histogramQueries` GoogleCloudContentwarehouseV1HistogramQuery[] — An expression specifying a histogram request against matching documents. Expression syntax is an aggregation function call with histogram facets and other options. The following aggregation functions are supported: * `count(string_histogram_facet)`: Count the number of matching entities for each distinct attribute value. Data types: * Histogram facet (aka filterable properties): Facet names with format .. Facets will have the format of: `a-zA-Z`. If the facet is a child facet, then the parent hierarchy needs to be specified separated by dots in the prefix after the schema id. Thus, the format for a multi- level facet is: .. . Example: schema123.root_parent_facet.middle_facet.child_facet * DocumentSchemaId: (with no schema id prefix) to get histograms for each document type (returns the schema id path, e.g. projects/12345/locations/us-west/documentSchemas/abc123). Example expression: * Document type counts: count('DocumentSchemaId') * For schema id, abc123, get the counts for MORTGAGE_TYPE: count('abc123.MORTGAGE_TYPE') - `requirePreciseResultSize` boolean — Controls if the histogram query requires the return of a precise count. Enable this flag may adversely impact performance. Defaults to true. - `histogramQuery` string — An expression specifies a histogram request against matching documents for searches. See SearchDocumentsRequest.histogram_queries for details about syntax. - `filters` GoogleCloudContentwarehouseV1HistogramQueryPropertyNameFilter - `documentSchemas` 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/{project_number}/locations/{location}/documentSchemas/{document_schema_id}. - `yAxis` 'HISTOGRAM_YAXIS_DOCUMENT' | 'HISTOGRAM_YAXIS_PROPERTY' — By default, the y_axis is HISTOGRAM_YAXIS_DOCUMENT if this field is not set. - `propertyNames` 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 is_filterable 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". - `documentQuery` GoogleCloudContentwarehouseV1DocumentQuery - `documentNameFilter` string[] — Search the documents in the list. Format: projects/{project_number}/locations/{location}/documents/{document_id}. - `isNlQuery` 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 `result_count` in SearchDocumentsRequest must be set. In addition, all other input fields related to search (pagination, histograms, etc.) will be ignored. - `documentSchemaNames` 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. - `fileTypeFilter` GoogleCloudContentwarehouseV1FileTypeFilter — Filter for the specific types of documents returned. - `fileType` 'FILE_TYPE_UNSPECIFIED' | 'ALL' | 'FOLDER' | 'DOCUMENT' | 'ROOT_FOLDER' — The type of files to return. - `timeFilters` GoogleCloudContentwarehouseV1TimeFilter[] — Documents created/updated within a range specified by this filter are searched against. - `timeRange` GoogleTypeInterval — Represents a time interval, encoded as a Timestamp start (inclusive) and a Timestamp end (exclusive). The start must be less than or equal to the end. When the start equals the end, the interval is empty (matches no time). When both start and end are unspecified, the interval matches any time. - `startTime` string, google-datetime — Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start. - `endTime` string, google-datetime — Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end. - `timeField` 'TIME_FIELD_UNSPECIFIED' | 'CREATE_TIME' | 'UPDATE_TIME' | 'DISPOSITION_TIME' — Specifies which time field to filter documents on. Defaults to TimeField.UPLOAD_TIME. - `queryContext` 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. - `documentCreatorFilter` 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. - `customPropertyFilter` string — This filter specifies a structured syntax to match against the [PropertyDefinition].is_filterable 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([property_name])` to perform a case insensitive match and `EMPTY([property_name])` 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` - `propertyFilter` GoogleCloudContentwarehouseV1PropertyFilter[] — This filter specifies a structured syntax to match against the PropertyDefinition.is_filterable marked as `true`. The relationship between the PropertyFilters is OR. - `condition` 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 text_values. 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([property_name])` to perform a case insensitive match and `EMPTY([property_name])` 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. - `documentSchemaName` string — The Document schema name Document.document_schema_name. Format: projects/{project_number}/locations/{location}/documentSchemas/{document_schema_id}. - `customWeightsMetadata` GoogleCloudContentwarehouseV1CustomWeightsMetadata — To support the custom weighting across document schemas. - `weightedSchemaProperties` GoogleCloudContentwarehouseV1WeightedSchemaProperty[] — List of schema and property name. Allows a maximum of 10 schemas to be specified for relevance boosting. - `documentSchemaName` string — The document schema name. - `propertyNames` string[] — The property definition names in the schema. - `folderNameFilter` string — Search all the documents under this specified folder. Format: projects/{project_number}/locations/{location}/documents/{document_id}. - `query` 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](https://google.aip.dev/160). 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([property_name])` to perform a case insensitive match and `EMPTY([property_name])` 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. `time_filters` and `folder_name_filter`. They are connected with `AND` operator under the hood. The maximum number of allowed characters is 255. - `pageSize` integer — A limit on the number of documents returned in the search results. Increasing this value above the default value of 10 can increase search response time. The value can be between 1 and 100. - `offset` integer — An integer that specifies the current offset (that is, starting result location, amongst the documents deemed by the API as relevant) in search results. This field is only considered if page_token is unset. The maximum allowed value is 5000. Otherwise an error is thrown. For example, 0 means to return results starting from the first matching document, and 10 means to return from the 11th document. This can be used for pagination, (for example, pageSize = 10 and offset = 10 means to return from the second page). ## Response `200` Successful response --- [API](https://skmtc.net/google/apis/contentwarehouse.md) · [All operations](https://skmtc.net/google/apis/contentwarehouse/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/google/contentwarehouse/versions/7a5c5ed93884/schema)