Avant de commencer
Pour ingérer des exemples de documents dans Document AI Warehouse, consultez le guide de démarrage rapide.
Définir vos données pour la recherche
Lorsque vous définissez vos schémas de document et que vous créez vos documents, il est important de réfléchir aux propriétés que vous souhaitez définir et à la façon dont elles seront utilisées avec la recherche, le cas échéant.
Marquez une propriété comme filtrable si vous souhaitez l'utiliser pour inclure ou exclure une partie des documents pour une recherche. Par exemple, vous pouvez rendre une propriété "Fournisseur" filtrable, car vos utilisateurs souhaitent rechercher des factures d'un fournisseur spécifique.
Si vous souhaitez créer un histogramme (voir l'exemple plus loin dans cette rubrique) sur une propriété, celle-ci doit être filtrable.
Marquez une propriété comme pouvant faire l'objet d'une recherche si elle contient des données que vos utilisateurs souhaiteront interroger lors d'une recherche par mot clé.
Recherche en texte intégral
La recherche en texte intégral consiste à récupérer tous les documents dont le texte interrogeable correspond aux mots clés de la recherche. L'utilisateur fournit une liste de mots clés (mots séparés par un espace), probablement saisis dans un champ de recherche de l'UI. Dans Document AI Warehouse, les mots clés sont traités et convertis en requête appropriée. Ce traitement supprime les mots vides ("le", "dans", "un", etc.) et réduit les mots restants à leur forme de base. La racinisation réduit le mot à une version courante de la formulation, de sorte que les variantes du mot correspondent. Par exemple : "travail", "travaillez", "travaillé".
Quelles données sont recherchées ?
- Le
plain_textdu document. - Si vous importez un objet Document AI, utilisez le
cloud_ai_document.textintégré. - Nom à afficher du document.
- Toutes les propriétés sur lesquelles il est possible d'effectuer une recherche.
La requête est partiellement compatible avec la syntaxe de style AIP Google. Plus précisément, la requête est compatible avec les littéraux, les opérateurs logiques, les opérateurs de négation, les opérateurs de comparaison et les fonctions.
- Littéraux : une valeur littérale brute (par exemple, "42", "Hugo") est une valeur à comparer. Elle effectue des recherches dans le texte intégral du document et dans les propriétés pouvant faire l'objet d'une recherche.
- Opérateurs logiques : "AND", "and", "OR" et "or" sont des opérateurs logiques binaires (exemple : "ingénieur OR développeur").
- Opérateurs de négation : "NOT" et "!" sont des opérateurs de négation (exemple : "NOT logiciel").
Opérateurs de comparaison : compatibles avec les opérateurs de comparaison binaires
=,!=,<,>,<=et>=pour les chaînes, les valeurs numériques, les énumérations et les valeurs booléennes. Prise en charge de l'opérateur "like"~~pour les chaînes. Il fournit une fonctionnalité de recherche sémantique en analysant, en effectuant une expansion des synonymes et en appliquant des racines aux mots de la requête saisie.Pour spécifier une propriété dans la requête, l'expression de gauche dans la comparaison doit être l'ID de propriété, y compris le parent. Le côté droit doit être constitué de littéraux. Par exemple,
\"projects/123/locations/us\".property_a < 1correspond aux résultats dont leproperty_aest inférieur à 1 dans le projet123et l'emplacementus. Les littéraux et l'expression de comparaison peuvent être associés dans une même requête (par exemple,software engineer \"projects/123/locations/us\".salary > 100).Fonctions : les fonctions compatibles sont
LOWER([property_name]), qui permet d'effectuer une correspondance sans distinction de casse, etEMPTY([property_name]), qui permet de filtrer en fonction de l'existence d'une clé.Accepte les expressions imbriquées connectées à l'aide de parenthèses et d'opérateurs logiques. L'opérateur logique par défaut est
ANDsi aucun opérateur n'est spécifié entre les expressions.
La requête peut être utilisée avec d'autres filtres, par exemple time_filters et folder_name_filter. Ils sont associés à l'opérateur AND en arrière-plan.
Les requêtes de recherche peuvent être filtrées par des paramètres supplémentaires tels que property, time, schema, folder et creator.
Appel à une demande de recherche
Pour appeler le service de recherche, vous devez utiliser une demande de recherche, qui est définie comme suit :
{
"requestMetadata": {
object (RequestMetadata)
},
"documentQuery": {
object (DocumentQuery)
},
"offset": integer,
"pageSize": integer,
"pageToken": string,
"orderBy": string,
"histogramQueries": [
{
object (HistogramQuery)
}
],
"requireTotalSize": boolean,
"totalResultSize": enum (TotalResultSize),
"qaSizeLimit": integer
}
Le champ parent doit être renseigné au format suivant :
/projects/PROJECT_ID/locations/LOCATION
Réponse à une demande de recherche
La réponse de recherche est définie comme suit :
{
"matchingDocuments": [
{
object (MatchingDocument)
}
],
"nextPageToken": string,
"totalSize": integer,
"metadata": {
object (ResponseMetadata)
},
"histogramQueryResults": [
{
object (HistogramQueryResult)
}
]
}
Requête de document
Le champ document_query est défini comme suit :
{
"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)
}
}
Le champ query est réservé aux mots de la requête de recherche de l'utilisateur. Elles proviennent généralement du champ de recherche de l'interface utilisateur.
Filtres
Document AI Warehouse propose différents filtres.
Filtre de période des documents
Le filtre de période de création et de modification fonctionne comme vous l'attendez : il trouve les documents correspondant aux mots clés dans une période spécifiée.
Un objet TimeFilter est utilisé pour spécifier la période. Il est défini comme suit :
{
"timeRange": {
object (Interval)
},
"timeField": enum (TimeField)
}
Le champ time_field vous permet d'indiquer si la période spécifiée dans time_range correspond à la date de création ou de dernière modification du document.
Le champ time_range spécifie la période sous la forme d'un Interval. Un Interval est défini comme suit :
{
"startTime": string,
"endTime": string
}
Filtre de créateur
Pour rechercher des documents créés par un ou plusieurs utilisateurs spécifiques, utilisez le filtre "Créateur". Exemple :
{
document_query {
query: "videogames director",
documentCreatorFilter: [
"diane@some_company.com",
"frank@some_company.com",
],
},
}
Filtre de propriété
Le filtre de propriété vous permet de spécifier des filtres sur l'une des propriétés que vous avez spécifiées dans un schéma, à condition que cette propriété ait été configurée pour être filtrable.
Par exemple, dans le secteur juridique, vous pouvez utiliser des filtres de propriété pour filtrer une propriété appelée COURT afin de rechercher uniquement les documents d'un tribunal spécifique.
Les filtres de propriété utilisent un objet PropertyFilter. Vous pouvez définir plusieurs filtres de propriété. Lorsque vous utilisez plusieurs filtres de propriété, ils sont combinés à l'aide de l'opérateur OR.
Un filtre de propriété est défini comme suit :
{
"documentSchemaName": string,
"condition": string
}
Les propriétés sont définies dans des schémas. Le champ documentSchemaName est donc l'endroit où vous spécifiez le schéma de la propriété que vous utilisez pour le filtrage. Dans le champ condition, vous spécifiez la logique souhaitée. Pour obtenir des exemples d'utilisation des champs documentSchemaName et condition, consultez les exemples précédents sur cette page.
Document correspondant
Un document correspondant contient un Document et un extrait (abordés plus loin). Le document renvoyé dans MatchingDocument n'est pas entièrement rempli. Il contient un minimum de données pour afficher une liste de résultats de recherche à l'utilisateur qui en fait la demande. Si l'utilisateur souhaite obtenir le document complet (par exemple, s'il a cliqué sur un résultat de recherche), il doit le récupérer à l'aide de l'API GetDocument.
Les champs Document suivants sont renseignés : Project number, Document id, Document schema id, Create time, Update time, Display name, Raw document file type, Reference id et Filterable properties.
Voici à quoi ressemblerait un document correspondant :
{
"document": {
object (Document)
},
"searchTextSnippet": string,
"qaResult": {
object (QAResult)
}
}
Classement/Tri
La requête de recherche vous permet de spécifier le mode de tri des résultats. Pour effectuer un tri, utilisez le champ order_by dans la requête de recherche. Les valeurs possibles pour ce champ sont les suivantes :
relevance desc: par pertinence décroissante (les meilleures correspondances sont en haut).upload_date desc: date de création du document dans l'ordre décroissant (les plus récents en haut).upload_date: date de création du document dans l'ordre croissant (le plus ancien en haut).update_date desc: date de la dernière mise à jour du document, dans l'ordre décroissant (les plus récents en haut).Update_date: date de la dernière mise à jour du document, par ordre croissant (du plus ancien au plus récent).
Si vous ne spécifiez pas de tri, mais que vous fournissez des mots clés de recherche, le tri est effectué par pertinence décroissante (les meilleures correspondances en haut). Si ni le tri ni les mots clés ne sont fournis, le tri par défaut est effectué par ordre décroissant de la date de mise à jour (les documents les plus récents en haut).
Pagination
La pagination est utile pour afficher une page de données à l'utilisateur final. Vous pouvez y spécifier la taille de la page et obtenir le nombre total de résultats à afficher à l'utilisateur (par exemple, "50 documents sur 300").
Définissez le champ page_size sur le nombre de résultats que vous souhaitez recevoir avec la requête de recherche. Cela peut correspondre aux exigences concernant la taille d'affichage des résultats de recherche dans l'UI.
Il existe deux mécanismes : le décalage et le jeton de page.
Un décalage correspond à l'index dans la liste des documents pouvant être renvoyés que vous souhaitez renvoyer. Par exemple, un décalage de 5 signifie que vous souhaitez obtenir les documents à partir du sixième. Vous incrémenterez probablement le décalage de la taille de la page pour la page de résultats suivante.
Vous pouvez également utiliser un jeton de page et ne pas avoir à vous soucier du calcul du prochain décalage. Après avoir effectué votre première requête de recherche, vous obtenez une réponse de recherche contenant le champ next_page_token. Si ce champ est vide, cela signifie qu'il n'y a plus de résultats. Si le champ n'est pas vide, utilisez ce jeton dans votre prochaine requête de recherche en définissant le champ page_token.
Certaines UI affichent le nombre de documents trouvés par la recherche. Par exemple, you are viewing 10 documents of 120. Pour obtenir le nombre de documents renvoyés, définissez le champ require_total_size boolean de la requête sur True.
Conseil : require_total_size=True entraîne une pénalité de performances. Définissez-le sur la requête de la première page, puis définissez-le sur false pour toutes les requêtes suivantes, en conservant le nombre total dans une variable locale.
Exemples de code
Python
Pour en savoir plus, consultez la documentation de référence de l'API Document AI Warehouse Python.
Pour vous authentifier auprès de Document AI Warehouse, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Pour en savoir plus, consultez la documentation de référence de l'API Document AI Warehouse Java.
Pour vous authentifier auprès de Document AI Warehouse, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Étapes suivantes
- Accédez à la recherche avancée pour découvrir comment utiliser les fonctionnalités de recherche avancée.
- Consultez la documentation de référence REST.