Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

搜索文档

前期准备

如需将示例文档注入到 Document AI Warehouse 中，请参阅快速入门指南。

定义用于搜索的数据

在定义文档架构和创建文档时，请务必考虑要定义哪些属性，以及这些属性将如何用于搜索（如果会用于搜索）。

如果您希望使用某个属性来包含或排除一部分文档以进行搜索，请将该属性标记为可过滤。例如，您可能会将表示“供应商”的属性标记为可过滤，因为您的用户希望搜索特定供应商的账单。

如果您希望针对某个属性构建直方图（请参阅本主题后面的示例），则该属性需要可过滤。

如果某个属性包含用户在关键字搜索期间想要查询的数据，请将该属性标记为可搜索。

全文搜索

全文搜索是指检索所有文档的过程，这些文档的可搜索文本中包含搜索关键字。用户提供一个关键字列表（以空格分隔的字词），这些关键字可能是用户在界面中的搜索字段中输入的。在 Document AI Warehouse 中，系统会对关键字进行处理并将其转换为适当的查询。此类处理会去除停用词（“the”“in”和“an”），并提取剩余字词的词干。词干提取会将字词缩减为字词的常见版本，以便匹配字词变体。例如：“work”“working”“worked”。

搜索范围内的数据

文档的 plain_text。
如果您要导入 Document AI 对象，请使用嵌入式 cloud_ai_document.text。
文档的 display_name。
所有可搜索的属性。

查询部分支持 Google AIP 样式语法。具体而言，查询支持字面量、逻辑运算符、否定运算符、比较运算符和函数。

字面量：裸字面量值（示例：“42”“Hugo”）是要匹配的值。它会在文档的全文和可搜索的属性中进行搜索。
逻辑运算符：“AND”“and”“OR”和“or”是二元逻辑运算符（示例：“engineer OR developer”）。
否定运算符：“NOT”和“!”是否定运算符（示例：“NOT software”）。
比较运算符：支持用于字符串、数值、枚举、布尔值的二元比较运算符=、!=、<、>、<=和>=。还支持用于字符串的 like 运算符 ~~。它通过解析、词干提取和对输入查询进行同义词扩展来提供语义搜索功能。

如需在查询中指定属性，比较中的左侧表达式必须是属性 ID（包括父级）。右侧必须是字面量。例如：\"projects/123/locations/us\".property_a < 1 会匹配项目 123 和 us 位置中 property_a 小于 1 的结果。字面量和比较表达式可以在单个查询中连接（示例：software engineer \"projects/123/locations/us\".salary > 100）。
函数：支持的函数有 LOWER([property_name]) 和 EMPTY([property_name])，前者用于执行不区分大小写的匹配，后者用于过滤是否存在键。
支持使用括号和逻辑运算符连接的嵌套表达式。如果表达式之间没有运算符，则默认逻辑运算符为 AND。

查询可以与其他过滤条件（例如 time_filters 和 folder_name_filter）一起使用。它们在后台使用 AND 运算符连接。

搜索查询可以按其他参数进行过滤，例如按 property、time、schema、folder 和 creator 进行过滤。

调用搜索请求

如需调用搜索服务，您必须使用搜索请求，其定义如下：

{
  "requestMetadata": {
    object (RequestMetadata)
  },
  "documentQuery": {
    object (DocumentQuery)
  },
  "offset": integer,
  "pageSize": integer,
  "pageToken": string,
  "orderBy": string,
  "histogramQueries": [
    {
      object (HistogramQuery)
    }
  ],
  "requireTotalSize": boolean,
  "totalResultSize": enum (TotalResultSize),
  "qaSizeLimit": integer
}

parent 字段必须按以下格式填写：

/projects/PROJECT_ID/locations/LOCATION

对搜索请求的响应

搜索响应的定义如下：

{
  "matchingDocuments": [
    {
      object (MatchingDocument)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer,
  "metadata": {
    object (ResponseMetadata)
  },
  "histogramQueryResults": [
    {
      object (HistogramQueryResult)
    }
  ]
}

文档查询

document_query 字段的定义如下：

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

query 字段用于请求用户的搜索查询字词。通常，这些字词来自界面中的搜索字段。

过滤条件

Document AI Warehouse 提供各种过滤条件。

文档时间过滤条件

创建和更新时间过滤条件与您预期的一致：它会查找在指定时间段内与关键字匹配的文档。

TimeFilter 对象用于指定时间范围，其定义如下：

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

time_field 字段用于指定 time_range 中指定的时间范围是文档的创建时间还是文档的上次更新时间。

time_range 字段将时间范围指定为 Interval。Interval 的定义如下：

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

创作者过滤条件

如需搜索由特定用户或多个用户创建的文档，请使用创建者过滤条件。例如：

  {
    document_query {
      query: "videogames director",
      documentCreatorFilter: [
        "diane@some_company.com",
        "frank@some_company.com",
      ],
    },
  }

属性过滤条件

借助属性过滤条件，您可以针对在架构中指定的任何属性指定过滤条件，前提是该属性已配置为可过滤。

例如，在法律行业中使用属性过滤条件可能会针对名为 COURT 的属性进行过滤，以仅搜索来自特定法院的文档。

属性过滤条件使用 PropertyFilter 对象。您可以拥有多个属性过滤条件。当您使用多个属性过滤条件时，它们会使用 OR 运算符组合在一起。属性过滤条件的定义如下：

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

属性在架构中定义。因此，您可以在 documentSchemaName 字段中指定用于过滤的属性的架构。在 condition 字段中，您可以指定所需的逻辑。如需查看使用 documentSchemaName 和 condition 字段的示例，请参阅本页面的前面示例。

匹配的文档

匹配的文档包含 Document 和代码段（稍后讨论）。MatchingDocument 中返回的文档不是完全填写的文档。它包含最少的数据，用于向请求用户显示搜索结果列表。如果需要完整文档（例如，如果用户点击了搜索结果），则应通过 GetDocument API 检索完整文档。

系统会填写以下 Document 字段：Project number、Document id、Document schema id、Create time、Update time、Display name、Raw document file type、Reference id 和 Filterable properties。

匹配的文档如下所示：

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

排名/排序

借助搜索请求，您可以指定结果的排序方式。如需排序，请使用搜索请求中的 order_by 字段。此字段的可能值包括：

relevance desc - 相关性降序，即最佳匹配项位于顶部。
upload_date desc - 文档创建日期降序（最新文档位于顶部）。
upload_date - 文档创建日期升序（最旧文档位于顶部）。
update_date desc - 文档上次更新日期降序（最新文档位于顶部）。
Update_date - 文档上次更新日期升序（最旧文档位于顶部）。

如果您未指定排序方式，但提供了搜索关键字，则系统会按相关性降序排序（最佳匹配项位于顶部）。如果既未提供排序方式也未提供关键字，则默认排序方式为按更新时间降序排序（最新文档位于顶部）。

分页

分页功能有助于向最终用户显示一页数据。您可以在此处指定页面大小，并获取结果大小的总计数以显示给用户（例如，“显示 300 个文档中的 50 个”）。

将 page_size 字段设置为您希望通过搜索请求接收的结果数。这可能与界面搜索结果显示大小的要求相对应。

有两种机制：偏移量和页面令牌。

偏移量是指您希望返回的可返回文档列表中的索引。例如，偏移量为 5 表示您希望返回第六个文档及之后的文档。您可能需要将偏移量增加页面大小，以获取下一页结果。

或者，您可以使用页面令牌，而不必担心计算下一个偏移量。发出第一个搜索请求后，您会收到包含 next_page_token 字段的搜索响应。如果此字段为空，则表示没有更多结果。如果该字段不为空，请通过设置 page_token 字段在下一个搜索请求中使用此令牌。

某些界面会显示搜索找到的文档数。例如，you are viewing 10 documents of 120。如需获取返回的文档计数，请将请求的 require_total_size boolean 字段设置为 True。提示：require_total_size=True 会降低性能。在第一个页面查询中设置此字段，然后在所有后续请求中将其设置为 false，并将总计数保留在局部变量中。

代码示例

Python

如需了解详情，请参阅 Document AI Warehouse Python API 参考文档。

如需向 Document AI Warehouse 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。


from google.cloud import contentwarehouse

# TODO(developer): Uncomment these variables before running the sample.
# project_number = 'YOUR_PROJECT_NUMBER'
# location = 'YOUR_PROJECT_LOCATION' # Format is 'us' or 'eu'
# document_query_text = 'YOUR_DOCUMENT_QUERY'
# user_id = 'user:YOUR_SERVICE_ACCOUNT_ID' # Format is "user:xxxx@example.com"


def search_documents_sample(
    project_number: str, location: str, document_query_text: str, user_id: str
) -> None:
    # Create a client
    client = contentwarehouse.DocumentServiceClient()

    # The full resource name of the location, e.g.:
    # projects/{project_number}/locations/{location}
    parent = client.common_location_path(project=project_number, location=location)

    # File Type Filter
    # Options: DOCUMENT, FOLDER
    file_type_filter = contentwarehouse.FileTypeFilter(
        file_type=contentwarehouse.FileTypeFilter.FileType.DOCUMENT
    )

    # Document Text Query
    document_query = contentwarehouse.DocumentQuery(
        query=document_query_text,
        file_type_filter=file_type_filter,
    )

    # Histogram Query
    histogram_query = contentwarehouse.HistogramQuery(
        histogram_query='count("DocumentSchemaId")'
    )

    request_metadata = contentwarehouse.RequestMetadata(
        user_info=contentwarehouse.UserInfo(id=user_id)
    )

    # Define request
    request = contentwarehouse.SearchDocumentsRequest(
        parent=parent,
        request_metadata=request_metadata,
        document_query=document_query,
        histogram_queries=[histogram_query],
    )

    # Make the request
    response = client.search_documents(request=request)

    # Print search results
    for matching_document in response.matching_documents:
        document = matching_document.document
        # Display name - schema display name.
        # Name.
        # Create date.
        # Snippet - keywords are highlighted with <b> & </b>.
        print(
            f"{document.display_name} - {document.document_schema_name}\n"
            f"{document.name}\n"
            f"{document.create_time}\n"
            f"{matching_document.search_text_snippet}\n"
        )

    # Print histogram
    for histogram_query_result in response.histogram_query_results:
        print(
            f"Histogram Query: {histogram_query_result.histogram_query}\n"
            f"| {'Schema':<70} | {'Count':<15} |"
        )
        for key, value in histogram_query_result.histogram.items():
            print(f"| {key:<70} | {value:<15} |")

Java

如需了解详情，请参阅 Document AI Warehouse Java API 参考文档。