Interroger des documents

Article
08/05/2023

Vous pouvez interroger des documents json arbitraires dans une collection en effectuant un billet sur la ressource « colls » dans Cosmos DB. La syntaxe sql de Cosmos DB fournit des opérateurs de requête hiérarchiques, relationnelles et spatiales pour interroger des documents et des projets. Pour plus d’informations sur l’interrogation de ressources dans Cosmos DB, consultez interrogation de ressources.

Requête

Méthode	URI de demande	Description
post	https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs	Notez que {databaseaccount} est le nom du compte Cosmos DB créé dans le cadre de votre abonnement. la valeur {db-id} est le nom/id généré par l’utilisateur de la base de données, et non l’ID généré par le système (rid). la valeur {coll-id} est le nom de la collection.

En-têtes

Consultez En-têtes de requête REST Azure Cosmos DB communs pour les en-têtes utilisés par toutes les requêtes Cosmos DB.

En-tête	Obligatoire	Type	Description
x-ms-documentdb-isquery	Obligatoire	Boolean	Doit être défini sur True, ce qui indique que post est une requête.
Content-Type	Obligatoire	String	Chaîne qui doit être définie sur application/query+json.
x-ms-max-item-count	Facultatif	Number	Entier indiquant le nombre maximal d’éléments à retourner par page. Les requêtes ne retournent pas plus que le nombre spécifié d’éléments par page, mais peuvent être inférieures en fonction du niveau de performance de la collection et de leur taille. Une valeur x-ms-max-item-count de -1 peut être spécifiée pour permettre au service de déterminer le nombre d’éléments optimal. Il s’agit de la valeur de configuration recommandée pour x-ms-max-item-count.
x-ms-continuation	Facultatif	String	Jeton de chaîne retourné pour les requêtes et les opérations de flux de lecture si d’autres résultats doivent être lus. Les clients peuvent récupérer la page de résultats suivante en renvoyant la demande avec l’en-tête de demande x-ms-continuation défini sur cette valeur.
x-ms-documentdb-query-enablecrosspartition	Facultatif	Booléen	Si la collection est partitionnée, elle doit être définie sur True pour permettre l’exécution sur plusieurs partitions. Les requêtes qui filtrent sur une clé de partition unique ou sur des collections à partition unique n’ont pas besoin de définir l’en-tête.
x-ms-consistency-level	Facultatif	String	Remplacement de niveau de cohérence. Les valeurs valides sont les suivantes : Strong, Bounded, Session ou Eventual (dans l’ordre du plus fort au plus faible). Le remplacement doit être identique ou plus faible que le niveau de cohérence configuré du compte.
x-ms-session-token	Facultatif	String	Jeton de chaîne utilisé avec la cohérence au niveau de la session. Les clients doivent faire écho à la dernière valeur de lecture de cet en-tête lors des demandes de lecture de cohérence de session.

Important

Pour l’en-tête Content-Type , n’incluez PAS l’ensemble de caractères (c’est-à-dire « application/query+json ; charset-utf-8 »). L’en-tête doit être exactement comme indiqué ci-dessus.

body

Propriété	Obligatoire	Type	Description
requête	Obligatoire	String	Contient le texte de la requête SQL. Pour plus d’informations sur la grammaire, consultez Grammaire SQL.
parameters	Obligatoire	Array	Tableau de valeurs de paramètres pour la requête.

{  
  "query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",  
  "parameters": [  
    {  
      "name": "@id",  
      "value": "AndersenFamily"  
    },  
    {  
      "name": "@city",  
      "value": "Seattle"  
    }  
  ]  
}

response

Retourne un tableau de documents qui correspondent à la requête demandée.

En-têtes

Consultez En-têtes de réponse REST Azure Cosmos DB communs pour les en-têtes retournés par toutes les réponses Cosmos DB. Les en-têtes de réponse importants sont les suivants :

Propriété	Type	Description
x-ms-continuation	String	Retourne un jeton pour extraire d’autres résultats de l’opération. Le client peut renvoyer la demande avec l’en-tête de demande x-ms-continuation contenant cette valeur pour reprendre l’exécution.
x-ms-request-charge	Number	Nombre d’unités de requête consommées par l’opération.

Codes d’état

Le tableau suivant répertorie les codes d'état courants renvoyés par cette opération. Pour obtenir la liste complète des codes status, consultez Codes d’état HTTP.

Code d'état HTTP	Description
200 OK	L'opération a réussi.
400 Demande incorrecte	La demande spécifiée a été spécifiée avec une syntaxe de SQL incorrecte, ou des en-têtes obligatoires sont manquants.

body

Propriété	Description
_Débarrasser	Id de ressource généré par le système pour la collection dans laquelle les documents résident.
_Compter	Nombre de documents renvoyés par l'opération Liste.
Documents	Tableau des documents renvoyés par l'opération.

Propriétés du document

Propriété	Description
id	Il s’agit du nom unique qui identifie le document, c’est-à-dire qu’aucun document ne peut partager le même ID. L’ID ne doit pas dépasser 255 caractères.
<custom>	Tout JSON défini par l'utilisateur.
_Débarrasser	Il s’agit d’une propriété générée par le système. L’ID de ressource (_rid) est un identificateur unique qui est également hiérarchique en fonction de la pile de ressources sur le modèle de ressource. Il est utilisé en interne pour le positionnement et la navigation de la ressource de document.
_Ts	Cette propriété est générée par le système. Elle spécifie l'horodateur de la dernière mise à jour de la ressource. La valeur est un horodateur.
_self	Cette propriété est générée par le système. Il s'agit de l'URI adressable unique pour la ressource.
_Etag	Il s’agit d’une propriété générée par le système qui spécifie l’etag de ressources requis pour le contrôle d’accès concurrentiel optimiste.
_Pièces jointes	Il s'agit d'une propriété générée par le système qui spécifie le chemin d'accès adressable pour la ressource de pièces jointes.

{  
  "_rid": "1KtjAImkcgw=",  
  "Documents": [  
    {  
      "id": "AndersenFamily",  
      "LastName": "Andersen",  
      "Parents": [  
        {  
          "FamilyName": null,  
          "FirstName": "Thomas"  
        },  
        {  
          "FamilyName": null,  
          "FirstName": "Mary Kay"  
        }  
      ],  
      "Children": [  
        {  
          "FamilyName": null,  
          "FirstName": "Henriette Thaulow",  
          "Gender": "female",  
          "Grade": 5,  
          "Pets": [  
            {  
              "GivenName": "Fluffy"  
            }  
          ]  
        }  
      ],  
      "Address": {  
        "State": "WA",  
        "County": "King",  
        "City": "Seattle"  
      },  
      "IsRegistered": true,  
      "_rid": "1KtjAImkcgwBAAAAAAAAAA==",  
      "_self": "dbs/1KtjAA==/colls/1KtjAImkcgw=/docs/1KtjAImkcgwBAAAAAAAAAA==/",  
      "_etag": "\"00003200-0000-0000-0000-56f9e84d0000\"",  
      "_ts": 1459218509,  
      "_attachments": "attachments/"  
    }  
  ],  
  "_count": 1  
}

Exemple

POST https://querydemo.documents.azure.com/dbs/1KtjAA==/colls/1KtjAImkcgw=/docs HTTP/1.1  
x-ms-continuation:   
x-ms-documentdb-isquery: True  
x-ms-documentdb-query-enablecrosspartition: True  
x-ms-date: Tue, 29 Mar 2016 02:28:32 GMT  
authorization: type%3dmaster%26ver%3d1.0%26sig%3drOlOhFh9plfC0ggZfmHtS3XepVitiIRsd6i1d9PnuW8%3d  
Cache-Control: no-cache  
User-Agent: Microsoft.Azure.Documents.Client/1.6.0.0  
x-ms-version: 2015-12-16  
Accept: application/json  
Content-Type: application/query+json  
Host: querydemo.documents.azure.com  
Cookie: x-ms-session-token#0=604; x-ms-session-token=604  
Content-Length: 170  
Expect: 100-continue  
  
{  
  "query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",  
  "parameters": [  
    {  
      "name": "@id",  
      "value": "AndersenFamily"  
    },  
    {  
      "name": "@city",  
      "value": "Seattle"  
    }  
  ]  
}

HTTP/1.1 201 Created  
Cache-Control: no-store, no-cache  
Pragma: no-cache  
Transfer-Encoding: chunked  
Content-Type: application/json  
Server: Microsoft-HTTPAPI/2.0  
Strict-Transport-Security: max-age=31536000  
x-ms-last-state-change-utc: Fri, 25 Mar 2016 22:39:02.501 GMT  
etag: "00003200-0000-0000-0000-56f9e84d0000"  
x-ms-resource-quota: documentSize=10240;documentsSize=10485760;collectionSize=10485760;  
x-ms-resource-usage: documentSize=0;documentsSize=1;collectionSize=1;  
x-ms-schemaversion: 1.1  
x-ms-alt-content-path: dbs/testdb/colls/testcoll  
x-ms-quorum-acked-lsn: 602  
x-ms-current-write-quorum: 3  
x-ms-current-replica-set-size: 4  
x-ms-request-charge: 12.38  
x-ms-serviceversion: version=1.6.52.5  
x-ms-activity-id: 856acd38-320d-47df-ab6f-9761bb987668  
x-ms-session-token: 0:603  
Set-Cookie: x-ms-session-token#0=603; Domain=querydemo.documents.azure.com; Path=/dbs/1KtjAA==/colls/1KtjAImkcgw=  
Set-Cookie: x-ms-session-token=603; Domain=querydemo.documents.azure.com; Path=/dbs/1KtjAA==/colls/1KtjAImkcgw=  
x-ms-gatewayversion: version=1.6.52.5  
Date: Tue, 29 Mar 2016 02:28:30 GMT  
  
{  
  "id": "AndersenFamily",  
  "LastName": "Andersen",  
  "Parents": [  
    {  
      "FamilyName": null,  
      "FirstName": "Thomas"  
    },  
    {  
      "FamilyName": null,  
      "FirstName": "Mary Kay"  
    }  
  ],  
  "Children": [  
    {  
      "FamilyName": null,  
      "FirstName": "Henriette Thaulow",  
      "Gender": "female",  
      "Grade": 5,  
      "Pets": [  
        {  
          "GivenName": "Fluffy"  
        }  
      ]  
    }  
  ],  
  "Address": {  
    "State": "WA",  
    "County": "King",  
    "City": "Seattle"  
  },  
  "IsRegistered": true,  
  "_rid": "1KtjAImkcgwBAAAAAAAAAA==",  
  "_self": "dbs/1KtjAA==/colls/1KtjAImkcgw=/docs/1KtjAImkcgwBAAAAAAAAAA==/",  
  "_etag": "\"00003200-0000-0000-0000-56f9e84d0000\"",  
  "_ts": 1459218509,  
  "_attachments": "attachments/"  
}

Share via

Interroger des documents

Requête

En-têtes

body

response

En-têtes

Codes d’état

body

Exemple

Voir aussi

Ressources supplémentaires