Colecciones
Azure Cosmos DB es una base de datos multimodelo distribuida globalmente que admite los modelos de datos de documento, gráfico y clave-valor. El contenido de esta sección es para crear, consultar y administrar recursos de recopilación mediante la API de SQL a través de REST.
La API REST admite operaciones CRUD básicas en los recursos de una cuenta de base de datos. Una colección es un contenedor de documentos JSON y la lógica de aplicaciones JavaScript asociada; es decir, procedimientos almacenados, desencadenadores y funciones definidas por el usuario. En este tema se describen las operaciones REST que se usan para administrar colecciones de documentos.
Nota
En estos artículos de referencia de API se muestra cómo crear recursos mediante la API del plano de datos de Azure Cosmos DB. Con la API del plano de datos, puede configurar opciones básicas, como la directiva de indexación, las claves de partición del mismo modo que puede usar los SDK de Cosmos DB. Si necesita compatibilidad completa con características para todos los recursos de Azure Cosmos DB, se recomienda usar el proveedor de recursos de Cosmos DB.
Una colección se asigna a un contenedor en Azure Cosmos DB. Por lo tanto, es una entidad facturable, donde el costo viene determinado por el rendimiento aprovisionado expresado en unidades de solicitud por segundo. Las colecciones pueden abarcar una o varias particiones o servidores y escalar y reducir verticalmente en términos de rendimiento. Las colecciones se particionan automáticamente en uno o más servidores físicos mediante Azure Cosmos DB.
Puesto que una colección es un recurso del sistema, tiene un esquema fijo. La ruta de acceso del URI de una colección se representa mediante intercalaciones en el modelo de recursos.
En el ejemplo siguiente se muestra la definición JSON de una colección:
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"kind": "Range",
"dataType": "String",
"precision": -1
},
{
"kind": "Range",
"dataType": "Number",
"precision": -1
}
]
}
],
"excludedPaths": []
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash"
},
"_rid": "PD5DALigDgw=",
"_ts": 1459200611,
"_self": "dbs/PD5DAA==/colls/PD5DALigDgw=/",
"_etag": "\"00005900-0000-0000-0000-56f9a2630000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}
| Propiedad | Descripción |
|---|---|
| id | Es el nombre único que identifica la nueva colección. |
| indexingPolicy | Es la configuración de la directiva de indexación para la recopilación. |
| partitionKey | Es la configuración de creación de particiones para la recopilación. |
| _Librar | Es 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 internamente para la colocación y la navegación del recurso de permiso. |
| _Ts | Es una propiedad generada por el sistema. Especifica la última marca de tiempo actualizada del recurso. El valor es una marca de tiempo. |
| _propio | Es una propiedad generada por el sistema. Es el URI direccionable único para el recurso. |
| _Etag | Es una propiedad generada por el sistema que representa la etag de recursos necesaria para el control de simultaneidad optimista. |
| _Doc | Es una propiedad generada por el sistema que especifica la ruta de acceso direccionable del recurso documents. |
| _sprocs | Es una propiedad generada por el sistema que especifica la ruta de acceso direccionable del recurso de procedimientos almacenados (sprocs). |
| _desencadenantes | Es una propiedad generada por el sistema que especifica la ruta de acceso direccionable del recurso triggers. |
| _Udfs | Es una propiedad generada por el sistema que especifica la ruta de acceso direccionable del recurso de funciones definidas por el usuario (udfs). |
| _Conflictos | Es una propiedad generada por el sistema que especifica la ruta de acceso direccionable del recurso de conflictos. Durante una operación en un recurso dentro de una colección, si se produce un conflicto, los usuarios pueden inspeccionar los recursos en conflicto realizando una operación GET en la ruta URI en conflicto. |
Propiedades en Directiva de indexación
| Propiedad | Descripción |
|---|---|
| Automático | Indica si la indexación automática está activada o desactivada. El valor predeterminado es True, por lo que se indexan todos los documentos. Establecer el valor en False permitiría la configuración manual de rutas de acceso de indexación. |
| indexingMode | De forma predeterminada, el modo de indexación es Coherente. Esto significa que la indexación se produce de forma sincrónica durante la inserción, sustitución o eliminación de documentos. Para que la indización se produzca de forma asincrónica, establezca el modo de indización en lazy. |
| includedPaths | La matriz que contiene las rutas de acceso del documento que se indexarán. De forma predeterminada, se incluyen dos rutas de acceso: /path, que especifica que se indexan todas las rutas de acceso del documento y la ruta de acceso _ts, que indexa para una comparación de intervalos de marca de tiempo. |
| excludedPaths | Matriz que contiene las rutas de acceso del documento que desea excluir de la indización. |
Propiedades en Rutas de acceso incluidas
| Propiedad | Descripción |
|---|---|
| path | Ruta de acceso a la que se aplica el comportamiento de indexación. Las rutas de acceso de índice comienzan con la raíz (/) y suelen terminar con el operador comodín ?, que indica que hay varios valores posibles para el prefijo. Por ejemplo, para atender la consulta SELECT * FROM Families F WHERE F.familyName = "Andersen", debe incluir una ruta de acceso de índice para /familyName/? en la directiva de índice de la colección. Las rutas de acceso del índice también pueden usar el operador comodín * para especificar el comportamiento de las rutas de acceso de forma recursiva en el prefijo. Por ejemplo, /payload/* se puede usar para incluir todo en la propiedad payload de la indexación. |
| dataType | Es el tipo de datos al que se aplica el comportamiento de indexación. Puede ser String, Number, Point, Polygon o LineString. Los valores Booleans y null se indexan automáticamente |
| kind | Tipo de índice. Los índices hash son útiles para las comparaciones de igualdad, mientras que los índices range son útiles para la igualdad, las comparaciones de intervalos y la ordenación. Los índices espaciales son útiles para las consultas espaciales. |
| precisión | Precisión del índice. Se puede establecer en -1 para la precisión máxima o entre 1 y 8 para Number y 1-100 para String. No es aplicable a los tipos de datos Point, Polygon y LineString . |
Propiedades en Rutas de acceso excluidas
| Propiedad | Descripción |
|---|---|
| path | Ruta de acceso que se excluye de la indexación. Las rutas de acceso de índice comienzan con la raíz (/) y suelen terminar con el operador * comodín. Por ejemplo, /payload/* puede usarse para excluir de la indexación a todo el contenido de la propiedad payload. |
Propiedades en Clave de partición
| Propiedad | Descripción |
|---|---|
| path | Matriz de rutas de acceso mediante las que se pueden particionar los datos de la colección. Las rutas de acceso no deben contener un carácter comodín ni una barra diagonal final. Por ejemplo, la propiedad JSON "AccountNumber" se especifica como "/AccountNumber". La matriz solo debe contener un único valor. |
| kind | Algoritmo utilizado para la creación de particiones. Solo se admite hash . |
Directiva de indexación
A medida que se agregan documentos a una colección, Cosmos DB indexa automáticamente los documentos, lo que permite consultar los documentos de forma predeterminada. Está en el nivel de colección en el que configura la directiva de indización. Puesto que la directiva de indización se establece en el nivel de colección, cada colección dentro de una base de datos puede tener distintas directivas de indización.
La directiva de indexación de una colección puede especificar las siguientes opciones:
Automático: puede elegir si desea que la colección indexe automáticamente todos los documentos o no. De forma predeterminada, todos los documentos se indexan automáticamente, pero puede desactivarla. Cuando se desactiva la indexación, solo se puede tener acceso a documentos a través de sus propios vínculos o mediante consultas con Id.
Modo de indexación: puede elegir entre actualizaciones de índice sincrónicas (coherentes), asincrónicas (diferidas) y sin indexación (Ninguno). De manera predeterminada, el índice se actualiza sincrónicamente en cada acción de inserción, reemplazo o eliminación realizada en un documento de la colección. Esta actualización permite que las consultas respeten el mismo nivel de coherencia que el de las lecturas del documento sin ningún retraso para que el índice se ponga al día.
Tipos de índice y precisión: el tipo o esquema usado para las entradas de índice tiene un impacto directo en el rendimiento y el almacenamiento de índices. En el caso de un esquema que usa una mayor precisión, las consultas normalmente son más rápidas. Sin embargo, también hay una mayor sobrecarga de almacenamiento para el índice. Elegir una menor precisión significa que es posible que se tengan que procesar más documentos durante la ejecución de la consulta, pero la sobrecarga del almacenamiento será menor.
Rutas de acceso de índice: en los documentos, puede elegir qué rutas de acceso se deben incluir o excluir de la indexación, lo que puede ofrecer un rendimiento de escritura mejorado y un almacenamiento de índices inferior para escenarios en los que se conocen los patrones de consulta de antemano.
En las tablas siguientes, se muestran algunas rutas de indexación de ejemplo y su uso en las consultas.
| Propiedad | Descripción |
|---|---|
| /* | Ruta de acceso predeterminada de la recopilación. Recursiva. Se aplica a la totalidad del árbol de documentos. |
| /prop/? | Ruta de acceso de índice necesaria para atender las consultas como la siguiente (con tipos hash o de intervalo respectivamente): SELECT * FROM collection c WHERE c.prop = "value" SELECT * FROM collection c WHERE c.prop > 5 SELECT * FROM collection c ORDER BY c.prop |
| /"prop"/* | Ruta de acceso del índice para todas las rutas de acceso situadas en la etiqueta especificada. Funciona con las siguientes consultas: SELECT * FROM collection c WHERE c.prop = "value" SELECT * FROM collection c WHERE c.prop.subprop > 5 SELECT * FROM collection c WHERE c.prop.subprop.nextprop = "value" SELECT * FROM collection c ORDER BY c.prop |
| /props/[]/? | Ruta de acceso de índice necesaria para atender consultas iteraciones y JOIN en matrices de escalares, como ["a", "b", "c"]: SELECT tag FROM tag IN collection.props WHERE tag = "value" SELECT tag FROM collection c JOIN tag IN c.props WHERE tag > 5 |
| /props/[]/subprop/? | Ruta de acceso de índice necesaria para atender consultas iteraciones y JOIN en matrices de objetos como [{subprop: "a"}, {subprop: "b"}]: SELECT tag FROM tag IN collection.props WHERE tag.subprop = "value" SELECT tag FROM collection c JOIN tag IN c.props WHERE tag.subprop = "value" |
| /prop/subprop/? | Ruta de acceso de índice necesaria para atender consultas (con las de tipo hash o de intervalo respectivamente): SELECT * FROM collection c WHERE c.prop.subprop = "value" SELECT * FROM collection c WHERE c.prop.subprop > 5 SELECT * FROM collection c ORDER BY c.prop.subprop |
Para más información sobre las directivas de indexación de Cosmos DB, consulte Directivas de indexación de Cosmos DB. En la documentación de la API REST, todos ejemplos utilizan la indización automática.
Ofertas y niveles de rendimiento
Cuando se crea una colección, también se crea un recurso Offer que hace referencia a la colección creada. El recurso Oferta contiene información de configuración sobre el rendimiento de la recopilación en unidades de solicitud por segundo y unidades de solicitud por minuto.
El nivel de rendimiento de una colección se puede cambiar mediante Reemplazar oferta.
Tareas
Puede hacer lo siguiente con colecciones de documentos: