Consulta de documentos
Para consultar documentos JSON arbitrarios en una colección, realice una publicación en el recurso "colls" de Cosmos DB. La sintaxis sql de Cosmos DB proporciona operadores de consulta jerárquicos, relacionales y espaciales para consultar y proyectar documentos. Para obtener más información sobre cómo consultar recursos en Cosmos DB, consulte Consulta de recursos.
Solicitud
| Método | URI de solicitud | Descripción |
|---|---|---|
| post | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs | tenga en cuenta que {databaseaccount} es el nombre de la cuenta de Cosmos DB creada en la suscripción. el valor {db-id} es el nombre o identificador generado por el usuario de la base de datos, no el identificador generado por el sistema (rid). el valor {coll-id} es el nombre de la colección. |
encabezados
Consulte Encabezados de solicitud REST comunes de Azure Cosmos DB para los encabezados que usan todas las solicitudes de Cosmos DB.
| Encabezado | Obligatorio | Tipo | Descripción |
|---|---|---|---|
| x-ms-documentdb-isquery | Obligatorio | Boolean | Debe establecerse en True, lo que indica que POST es una consulta. |
| Content-Type | Obligatorio | String | Cadena que se debe establecer en application/query+json. |
| x-ms-max-item-count | Opcionales | Number | Entero que indica el número máximo de elementos que se van a devolver por página. Las consultas no devolverán más del número especificado de elementos por página, pero podrían ser menos en función del nivel de rendimiento de la colección y sus tamaños. Se puede especificar un recuento de elementos x-ms-max-item-count de -1 para permitir que el servicio determine el recuento óptimo de elementos. Es el valor de configuración recomendado para x-ms-max-item-count. |
| x-ms-continuation | Opcionales | String | Un token de cadena devuelto para las consultas y las operaciones de fuente de lectura si hay más resultados que se van a leer. Los clientes pueden recuperar la siguiente página de resultados reenviando la solicitud con el encabezado de solicitud x-ms-continuation establecido en este valor. |
| x-ms-documentdb-query-enablecrosspartition | Opcionales | Boolean | Si la colección tiene particiones, debe establecerse en True para permitir la ejecución en varias particiones. Las consultas que filtran por una sola clave de partición o en colecciones con particiones únicas no necesitan establecer el encabezado. |
| x-ms-consistency-level | Opcionales | String | Es el nivel que reemplazar al nivel de coherencia anterior. Los valores válidos son: Strong, Bounded, Session o Eventual (en orden de mayor a menor). La invalidación debe ser la misma o más débil que el nivel de coherencia configurado de la cuenta. |
| x-ms-session-token | Opcionales | String | Token de cadena usado con coherencia de nivel de sesión. Los clientes deben hacer eco del último valor de lectura de este encabezado durante las solicitudes de lectura para la coherencia de la sesión. |
Importante
Para el Content-Type encabezado NO se incluye el conjunto de caracteres (es decir, "application/query+json; charset-utf-8"). El encabezado debe ser exactamente como se muestra anteriormente.
Body
| Propiedad | Obligatorio | Tipo | Descripción |
|---|---|---|---|
| consulta | Obligatorio | String | Contiene el texto de la consulta SQL. Para la gramática, consulte Gramática sql. |
| parameters | Obligatorio | Array | Matriz de valores de parámetro para la consulta. |
{
"query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",
"parameters": [
{
"name": "@id",
"value": "AndersenFamily"
},
{
"name": "@city",
"value": "Seattle"
}
]
}
Response
Devuelve una matriz de documentos que coinciden con la consulta solicitada.
encabezados
Consulte Encabezados de respuesta REST comunes de Azure Cosmos DB para ver los encabezados devueltos por todas las respuestas de Cosmos DB. Los encabezados de respuesta importantes son:
| Propiedad | Tipo | Descripción |
|---|---|---|
| x-ms-continuation | String | Devuelve un token para capturar más resultados de la operación. El cliente puede volver a enviar la solicitud con el encabezado de solicitud x-ms-continuation que contiene este valor para reanudar la ejecución. |
| x-ms-request-charge | Number | Número de unidades de solicitud consumidas por la operación. |
Códigos de estado
La tabla siguiente muestra los códigos de estado comunes que devuelve esta operación. Para obtener una lista completa de los códigos de estado, consulte Códigos de estado HTTP.
| Código de estado HTTP | Descripción |
|---|---|
| 200 OK | La operación se realizó correctamente. |
| 400 - Solicitud incorrecta | La solicitud especificada se especificó con una sintaxis SQL incorrecta o faltaban encabezados necesarios. |
Body
| Propiedad | Descripción |
|---|---|
| _Librar | Es el identificador del recurso generado por el sistema para la colección donde residen los documentos. |
| _Contar | La cantidad de documentos que devuelve la operación de lista. |
| Documentos | La matriz de documentos devuelta por la operación. |
Propiedades del documento
| Propiedad | Descripción |
|---|---|
| id | Este es el nombre único que identifica el documento, es decir, ningún documento puede compartir el mismo identificador. El identificador no debe superar los 255 caracteres. |
| <custom> | Cualquier JSON definida por el usuario. |
| _Librar | Se trata de una propiedad generada por el sistema. El identificador de recurso (_rid) es un identificador único que también es jerárquico por la pila de recursos en el modelo de recursos. Se usa de forma interna para la ubicación y la navegación del recurso de documento. |
| _Ts | Se trata de una propiedad generada por el sistema. Especifica la última marca de tiempo actualizada del recurso. El valor es una marca de tiempo. |
| _propio | Se trata de una propiedad generada por el sistema. Es el URI direccionable único para el recurso. |
| _Etag | Se trata de una propiedad generada por el sistema que especifica la etag de recursos necesaria para el control de simultaneidad optimista. |
| _Accesorios | Se trata de una propiedad generada por el sistema que especifica la ruta de acceso direccionable del recurso de datos adjuntos. |
{
"_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
}
Ejemplo
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/"
}