Consultar Documentos

Artigo
08/05/2023

Você pode consultar documentos json arbitrários em uma coleção executando uma postagem no recurso "colls" no Cosmos DB. A sintaxe sql do Cosmos DB fornece operadores de consulta hierárquica, relacional e espacial para consultar e projetar documentos. Para obter mais informações sobre como consultar recursos no Cosmos DB, consulte consultando recursos.

Solicitação

Método	URI da solicitação	Descrição
post	https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs	observe que {databaseaccount} é o nome da conta do Cosmos DB criada em sua assinatura. o valor {db-id} é o nome/id gerado pelo usuário do banco de dados, não a ID gerada pelo sistema (rid). o valor {coll-id} é o nome da coleção.

Cabeçalhos

Confira Cabeçalhos comuns de solicitação REST do Azure Cosmos DB para cabeçalhos usados por todas as solicitações do Cosmos DB.

Cabeçalho	Obrigatório	Type	Descrição
x-ms-documentdb-isquery	Obrigatório	Boolean	Deve ser definido como True indicando que POST é uma consulta.
Content-Type	Obrigatório	String	Uma cadeia de caracteres que deve ser definida como application/query+json.
x-ms-max-item-count	Opcional	Número	Um inteiro que indica o número máximo de itens a serem retornados por página. As consultas não retornarão mais do que o número especificado de itens por página, mas podem ser menos dependendo da camada de desempenho da coleção e de seus tamanhos. Uma contagem de itens x-ms-max de -1 pode ser especificada para permitir que o serviço determine a contagem de itens ideal. É o valor de configuração recomendado para x-ms-max-item-count.
x-ms-continuation	Opcional	String	Um token de cadeia de caracteres retornado para consultas e operações de feed de leitura se houver mais resultados a serem lidos. Os clientes podem recuperar a próxima página de resultados reenviando a solicitação com o cabeçalho de solicitação x-ms-continuation definido como esse valor.
x-ms-documentdb-query-enablecrosspartition	Opcional	Boolean	Se a coleção for particionada, isso deverá ser definido como True para permitir a execução em várias partições. Consultas que filtram em uma única chave de partição ou em coleções particionadas única não precisam definir o cabeçalho.
x-ms-consistency-level	Opcional	String	Esta é a substituição de nível consistente. Os valores válidos são: Strong, Bounded, Session ou Eventual (na ordem de mais forte para mais fraco). A substituição deve ser a mesma ou mais fraca do que o nível de consistência configurado da conta.
x-ms-session-token	Opcional	String	Um token de cadeia de caracteres usado com consistência de nível de sessão. Os clientes devem ecoar o valor de leitura mais recente desse cabeçalho durante solicitações de leitura para consistência de sessão.

Importante

Para o Content-Type cabeçalho, NÃO inclua o conjunto de caracteres (ou seja, "application/query+json; charset-utf-8"). O cabeçalho deve ser exatamente como mostrado acima.

Corpo

Propriedade	Obrigatório	Type	Descrição
consulta	Obrigatório	String	Contém o texto da consulta SQL. Para gramática, consulte Gramática sql.
parameters	Obrigatório	Array	Uma matriz de valores de parâmetro para a consulta.

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

Resposta

Retorna uma matriz de documentos que correspondem à consulta solicitada.

Cabeçalhos

Consulte Cabeçalhos comuns de resposta REST do Azure Cosmos DB para obter cabeçalhos retornados por todas as respostas do Cosmos DB. Os cabeçalhos de resposta importantes são:

Propriedade	Type	Descrição
x-ms-continuation	String	Retorna um token para buscar mais resultados da operação. O cliente pode reenviar a solicitação com o cabeçalho de solicitação x-ms-continuation que contém esse valor para retomar a execução.
x-ms-request-charge	Número	O número de unidades de solicitação consumidas pela operação.

Códigos de status

A tabela a seguir lista os códigos de status comuns retornados por esta operação. Para obter uma lista completa de códigos de status, consulte Códigos de status HTTP.

Código de status HTTP	Descrição
200 OK	A operação foi bem-sucedida.
400 Solicitação Inválida	A solicitação especificada foi definida com uma sintaxe de SQL incorreta ou com cabeçalhos necessários ausentes.

Corpo

Propriedade	Descrição
_Livrar	Essa é a ID de recursos gerada pelo sistema para a coleção onde residem os documentos.
_Contar	Esse é o número de documentos retornados pela operação de lista.
Documentos	A matriz de documentos retornada pela operação.

Propriedades do Documento

Propriedade	Descrição
id	Esse é o nome exclusivo que identifica o documento, ou seja, nenhum documento pode compartilhar a mesma ID. A ID não deve exceder 255 caracteres.
<custom>	Qualquer JSON definido pelo usuário.
_Livrar	Essa é uma propriedade gerada pelo sistema. A ID do recurso (_rid) é um identificador exclusivo que também é hierárquico de acordo com a pilha de recursos no modelo de recurso. Ela é usada internamente para posicionamento e navegação do recurso de documento.
_Ts	Essa é uma propriedade gerada pelo sistema. Especifica o último carimbo de data/hora atualizado do recurso. O valor é um carimbo de data/hora.
_Auto	Essa é uma propriedade gerada pelo sistema. É o URI endereçável exclusivo do recurso.
_Etag	Essa é uma propriedade gerada pelo sistema que especifica a etag de recurso necessária para o controle de simultaneidade otimista.
_Anexos	Esta é uma propriedade gerada adequadamente que especifica o caminho endereçável para o recurso de anexos.

{  
  "_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  
}

Exemplo

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

Consultar Documentos

Solicitação

Cabeçalhos

Corpo

Resposta

Cabeçalhos

Códigos de status

Corpo

Exemplo

Consulte Também

Recursos adicionais