Antes de comenzar
Para transferir documentos de muestra a Document AI Warehouse, consulta la Guía de inicio rápido.
Define tus datos para la búsqueda
Cuando definas los esquemas de documentos y crees tus documentos, es importante tener en cuenta qué propiedades deseas definir y cómo se usarán con la búsqueda, si es que se usan.
Marca una propiedad como filtrable si deseas usarla para incluir o excluir una parte de los documentos para una búsqueda. Por ejemplo, puedes hacer que una propiedad que represente un "Proveedor" sea filtrable porque tus usuarios quieren buscar facturas de un proveedor específico.
Si deseas construir un histograma (consulta el ejemplo más adelante en este tema) en una propiedad, esta debe ser filtrable.
Marca una propiedad como apta para búsqueda si tiene datos que tus usuarios querrán consultar durante una búsqueda de palabras clave.
Búsqueda en el texto completo
La búsqueda en el texto completo es el proceso de recuperación de todos los documentos que coinciden con las palabras clave de búsqueda en su texto apto para búsqueda. El usuario proporciona una lista de palabras clave (palabras separadas por un espacio en blanco), presumiblemente escritas en un campo de búsqueda en la IU. En Document AI Warehouse, las palabras clave se procesan y se convierten en una consulta adecuada. Este procesamiento quita las palabras vacías ("el", "en" y "un") y aplica el stemming a las palabras restantes. El stemming reduce la palabra a una versión común de la redacción, de modo que coincida con la variación de la palabra. Por ejemplo: "trabajo", "trabajando", "trabajó".
¿Qué datos se buscan?
- El
plain_textdel documento - Si importas un objeto de Document AI, usa el
cloud_ai_document.textintegrado. - El display_name del documento
- Todas las propiedades aptas para búsqueda
La consulta admite parcialmente la sintaxis de estilo de Google AIP. En particular, la consulta admite literales, operadores lógicos, operadores de negación, operadores de comparación y funciones.
- Literales: Un valor literal simple (ejemplos: "42", "Hugo") es un valor que se debe comparar. Busca en el texto completo del documento y en las propiedades aptas para búsqueda.
- Operadores lógicos: "AND", "and", "OR" y "or" son operadores lógicos binarios (ejemplo: "engineer OR developer").
- Operadores de negación: "NOT" y "!" son operadores de negación (ejemplo: "NOT software").
Operadores de comparación: admiten los operadores de comparación binaria
=,!=,<,>,<=y>=para cadenas, números, enumeraciones, booleanos. También admiten el operador like~~para cadenas. Proporciona funcionalidad de búsqueda semántica mediante el análisis, el stemming y la expansión de sinónimos en la consulta de entrada.Para especificar una propiedad en la consulta, la expresión del lado izquierdo de la comparación debe ser el ID de la propiedad, incluido el elemento superior. El lado derecho debe ser literales. Por ejemplo:
\"projects/123/locations/us\".property_a < 1coincide con los resultados cuyoproperty_aes menor que 1 en el proyecto123y la ubicaciónus. Los literales y la expresión de comparación se pueden conectar en una sola consulta (ejemplo:software engineer \"projects/123/locations/us\".salary > 100).Funciones: Las funciones admitidas son
LOWER([property_name])para realizar una coincidencia que no distinga mayúsculas de minúsculas yEMPTY([property_name])para filtrar la existencia de una clave.Admite expresiones anidadas conectadas con paréntesis y operadores lógicos. El operador lógico predeterminado es
ANDsi no hay operadores entre las expresiones.
La consulta se puede usar con otros filtros, por ejemplo, time_filters y folder_name_filter. Se conectan con el operador AND en niveles profundos.
Las consultas de búsqueda se pueden filtrar con parámetros adicionales, como property, time, schema, folder y creator.
Llamada a una solicitud de búsqueda
Para llamar al servicio de búsqueda, debes usar una solicitud de búsqueda, que se define de la siguiente manera:
{
"requestMetadata": {
object (RequestMetadata)
},
"documentQuery": {
object (DocumentQuery)
},
"offset": integer,
"pageSize": integer,
"pageToken": string,
"orderBy": string,
"histogramQueries": [
{
object (HistogramQuery)
}
],
"requireTotalSize": boolean,
"totalResultSize": enum (TotalResultSize),
"qaSizeLimit": integer
}
El campo parent debe completarse con el siguiente formato:
/projects/PROJECT_ID/locations/LOCATION
Respuesta a una solicitud de búsqueda
La respuesta de búsqueda se define de la siguiente manera:
{
"matchingDocuments": [
{
object (MatchingDocument)
}
],
"nextPageToken": string,
"totalSize": integer,
"metadata": {
object (ResponseMetadata)
},
"histogramQueryResults": [
{
object (HistogramQueryResult)
}
]
}
Consulta de documentos
El campo document_query se define de la siguiente manera:
{
"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)
}
}
El campo query es para las palabras de búsqueda del usuario solicitante. Por lo general, provienen del campo de búsqueda de la IU.
Filtros
Document AI Warehouse ofrece una variedad de filtros.
Filtro de tiempo de documentos
El filtro de hora de creación y actualización es exactamente lo que esperarías: encuentra documentos que coinciden con las palabras clave dentro de un período especificado.
Se usa un objeto TimeFilter para especificar el período, y se define de la siguiente manera:
{
"timeRange": {
object (Interval)
},
"timeField": enum (TimeField)
}
El campo time_field es donde especificas si el período especificado en time_range es para la hora de creación del documento o la hora de la última actualización del documento.
El campo time_range especifica el período como un Interval. Un Interval se define de la siguiente manera:
{
"startTime": string,
"endTime": string
}
Filtro de creador
Para buscar documentos creados por un usuario o usuarios específicos, usa el filtro de creador. Por ejemplo:
{
document_query {
query: "videogames director",
documentCreatorFilter: [
"diane@some_company.com",
"frank@some_company.com",
],
},
}
Filtro de propiedades
El filtro de propiedades te permite especificar filtros en cualquiera de las propiedades que especificaste en un esquema, siempre que esa propiedad se haya configurado como filtrable.
Por ejemplo, el uso de filtros de propiedades en la industria legal podría filtrar una propiedad llamada COURT para buscar solo documentos de un tribunal en particular.
Los filtros de propiedades usan un objeto PropertyFilter. Puedes tener más de un filtro de propiedades. Cuando usas varios filtros de propiedades, se combinan con el operador OR.
Un filtro de propiedades se define de la siguiente manera:
{
"documentSchemaName": string,
"condition": string
}
Las propiedades se definen en esquemas. Por lo tanto, el campo documentSchemaName es donde especificas el esquema de la propiedad que usas para filtrar. En el campo condition, especificas la lógica deseada. Para ver ejemplos del uso de los campos documentSchemaName y condition, consulta los ejemplos anteriores de esta página.
Documento coincidente
Un documento coincidente contiene un Document y un fragmento (que se analizará más adelante). El documento que se muestra en MatchingDocument no es un documento completamente completado. Contiene datos mínimos para mostrar una lista de resultados de la búsqueda al usuario solicitante. Si se desea el documento completo (por ejemplo, si el usuario hizo clic en un resultado de la búsqueda), se debe recuperar a través de la API de GetDocument.
Se completan los siguientes campos Document: Project number, Document id, Document schema id, Create time, Update time, Display name, Raw document file type, Reference id y Filterable properties.
Un documento coincidente se vería de la siguiente manera:
{
"document": {
object (Document)
},
"searchTextSnippet": string,
"qaResult": {
object (QAResult)
}
}
Clasificación/orden
La solicitud de búsqueda te permite especificar cómo deseas que se ordenen los resultados. Para ordenar, usa el campo order_by en la solicitud de búsqueda. Los valores posibles para este campo incluyen lo siguiente:
relevance desc: Pertinencia descendente, es decir, las mejores coincidencias están en la parte superior.upload_date desc: La fecha en que se creó el documento en orden descendente (el más reciente en la parte superior).upload_date: La fecha en que se creó el documento en orden ascendente (el más antiguo en la parte superior).update_date desc- la fecha en que se actualizó el documento por última vez en orden descendente (el más reciente en la parte superior).Update_date: La fecha en que se actualizó el documento por última vez en orden ascendente (el más antiguo en la parte superior).
Si no especificas un orden, pero proporcionas palabras clave de búsqueda, el orden es por pertinencia descendente (las mejores coincidencias en la parte superior). Si no se proporcionan el orden ni las palabras clave, el orden predeterminado es por hora de actualización descendente (los documentos más recientes en la parte superior).
Paginación
La paginación es útil para mostrar una página de datos al usuario final. Aquí puedes especificar el tamaño de la página y obtener un recuento total del tamaño del resultado para mostrarlo al usuario (por ejemplo, "Se muestran 50 documentos de 300").
Configura el campo page_size con la cantidad deseada de resultados que deseas recibir con la solicitud de búsqueda. Esto podría corresponder a los requisitos del tamaño de visualización de los resultados de la búsqueda de la IU.
Existen dos mecanismos: el token de desplazamiento y el token de página.
Un desplazamiento es el índice en la lista de documentos que se pueden mostrar que deseas que se muestren. Por ejemplo, un desplazamiento de 5 significa que deseas el sexto documento en adelante. Presumiblemente, aumentarías el desplazamiento según el tamaño de la página para la siguiente página de resultados.
Como alternativa, puedes usar un token de página y no tener que preocuparte por calcular el siguiente desplazamiento. Después de realizar tu primera solicitud de búsqueda, obtendrás una respuesta de búsqueda que contiene el campo next_page_token. Si este campo está vacío, no hay más resultados. Si el campo no está vacío, usa este token en tu próxima solicitud de búsqueda configurando el campo page_token.
Algunas IUs muestran el recuento de documentos que encontró la búsqueda. Por ejemplo, you are viewing 10 documents of 120. Para obtener un recuento de documentos que se muestre, configura el campo require_total_size boolean de la solicitud como True.
Sugerencia: require_total_size=True conlleva una penalización de rendimiento. Configura esto en la consulta de la primera página y, luego, configúralo como false en todas las solicitudes posteriores, manteniendo el recuento total en una variable local.
Muestras de código
Python
Para obtener más información, consulta la documentación de referenciaPython de la API de Document AI Warehouse.
Para autenticarte en Document AI Warehouse, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para obtener más información, consulta la documentación de referenciaJava de la API de Document AI Warehouse.
Para autenticarte en Document AI Warehouse, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.