Coleções
O Azure Cosmos DB é uma base de dados de vários modelos distribuída globalmente que suporta os modelos de dados de documentos, gráficos e chave-valor. O conteúdo desta secção destina-se a criar, consultar e gerir recursos de coleção com a API SQL através de REST.
A API REST suporta operações CRUD básicas nos recursos numa conta de base de dados. Uma coleção é um contentor de documentos JSON e lógica de aplicação JavaScript associada, ou seja, procedimentos armazenados, acionadores e funções definidas pelo utilizador. Este tópico descreve as operações REST utilizadas para gerir coleções de documentos.
Nota
Estes artigos de referência da API mostram como criar recursos com a API do plano de dados do Azure Cosmos DB. Com a API do plano de dados, pode configurar opções básicas, como a política de indexação, chaves de partição tal como com os SDKs do Cosmos DB. Se precisar de suporte completo de funcionalidades para todos os recursos do Azure Cosmos DB, recomendamos que utilize o Fornecedor de Recursos do Cosmos DB.
Uma coleção mapeia para um contentor no Azure Cosmos DB. Por conseguinte, é uma entidade faturável, em que o custo é determinado pelo débito aprovisionado expresso em unidades de pedido por segundo. As coleções podem abranger uma ou mais partições/servidores e aumentar e reduzir verticalmente em termos de débito. As coleções são particionadas automaticamente num ou mais servidores físicos pelo Azure Cosmos DB.
Uma vez que uma coleção é um recurso de sistema, tem um esquema fixo. O caminho URI de uma coleção é representado por agrupamentos no modelo de recursos.
O exemplo seguinte ilustra a definição JSON de uma coleção:
{
"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/"
}
| Propriedade | Descrição |
|---|---|
| id | É o nome exclusivo que identifica a nova coleção. |
| indexingPolicy | São as definições de política de indexação da coleção. |
| partitionKey | São as definições de configuração de criação de partições para a coleção. |
| _rid | É uma propriedade gerada pelo sistema. O ID do recurso (_rid) é um identificador exclusivo que também é hierárquico de acordo com a pilha de recursos no modelo de recursos. É utilizado internamente para colocação e navegação do recurso de permissão. |
| _ts | É uma propriedade gerada pelo sistema. Especifica o último carimbo de data/hora atualizado do recurso. O valor é um carimbo de data/hora. |
| _self | É uma propriedade gerada pelo sistema. É o URI endereçável exclusivo para o recurso. |
| _etag | É uma propriedade gerada pelo sistema que representa a etag de recursos necessária para o controlo de simultaneidade otimista. |
| _doc | É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso de documentos. |
| _sprocs | É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso de procedimentos armazenados (sprocs). |
| _triggers | É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso de acionadores. |
| _udfs | É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso de funções definidas pelo utilizador (udfs). |
| _conflicts | É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso de conflitos. Durante uma operação num recurso numa coleção, se ocorrer um conflito, os utilizadores podem inspecionar os recursos em conflito ao efetuar um GET no caminho do URI de conflitos. |
Propriedades em Política de Indexação
| Propriedade | Descrição |
|---|---|
| automático | Indica se a indexação automática está ativada ou desativada. O valor predefinido é Verdadeiro, pelo que todos os documentos são indexados. Definir o valor como Falso permitiria a configuração manual dos caminhos de indexação. |
| indexingMode | Por predefinição, o modo de indexação é Consistente. Isto significa que a indexação ocorre de forma síncrona durante a inserção, substituição ou eliminação de documentos. Para que a indexação ocorra de forma assíncrona, defina o modo de indexação como em diferido. |
| includedPaths | A matriz que contém caminhos de documento a indexar. Por predefinição, estão incluídos dois caminhos: o /path, que especifica que todos os caminhos do documento são indexados, e o caminho _ts, que indexa para uma comparação de intervalo de carimbo de data/hora. |
| excludedPaths | A matriz que contém caminhos de documento a serem excluídos da indexação. |
Propriedades em Caminhos Incluídos
| Propriedade | Descrição |
|---|---|
| caminho | Caminho ao qual o comportamento de indexação se aplica. Os caminhos de índice começam com a raiz (/) e normalmente terminam com o ? operador wildcard, indicando que existem vários valores possíveis para o prefixo. Por exemplo, para servir SELECT * FROM Families F WHERE F.familyName = "Andersen", tem de incluir um caminho de índice para /familyName/? na política de índice da coleção. Os caminhos de índice também podem utilizar o operador de carateres universais * para especificar o comportamento dos caminhos de forma recursiva no prefixo. Por exemplo, /payload/* pode ser utilizado para incluir tudo na propriedade payload da indexação. |
| dataType | É o tipo de dados ao qual o comportamento de indexação é aplicado. Pode ser Cadeia, Número, Ponto, Polígono ou LineString. Os booleanos e os nulos são indexados automaticamente |
| tipo | O tipo de índice. Os índices de Hash são úteis para comparações de igualdade, enquanto os índices range são úteis para a igualdade, comparações de gama e triagem. Os índices espaciais são úteis para consultas espaciais. |
| precisão | A precisão do índice. Pode ser definido como -1 para precisão máxima ou entre 1-8 para Número e 1-100 para Cadeia. Não aplicável aos tipos de dados Point, Polygon e LineString . |
Propriedades em Caminhos Excluídos
| Propriedade | Descrição |
|---|---|
| caminho | Caminho excluído da indexação. Os caminhos de índice começam com a raiz (/) e normalmente terminam com o operador de carateres universais *. Por exemplo, /payload/* pode ser utilizado para excluir tudo na propriedade payload da indexação. |
Propriedades em Chave de Partição
| Propriedade | Descrição |
|---|---|
| caminho | Uma matriz de caminhos com os quais os dados na coleção podem ser particionados. Os caminhos não podem conter um caráter universal ou uma barra à direita. Por exemplo, a propriedade JSON "AccountNumber" é especificada como "/AccountNumber". A matriz tem de conter apenas um único valor. |
| tipo | O algoritmo utilizado para a criação de partições. Apenas o Hash é suportado. |
Política de Indexação
À medida que os documentos são adicionados a uma coleção, o Cosmos DB indexa automaticamente os documentos, permitindo assim que os documentos sejam consultados. É ao nível da coleção que configura a política de indexação. Uma vez que a política de indexação é definida ao nível da coleção, cada coleção numa base de dados pode ter políticas de indexação diferentes.
A política de indexação de uma coleção pode especificar as seguintes opções:
Automático: pode escolher se pretende que a coleção indexe automaticamente todos os documentos ou não. Por predefinição, todos os documentos são indexados automaticamente, mas pode optar por desativá-lo. Quando a indexação é desativada, os documentos só podem ser acedidos através das respetivas autoligações ou através de consultas que utilizem o ID.
Modo de Indexação: pode escolher entre atualizações de índice síncronas (Consistentes), assíncronas (Em diferidas) e sem indexação (Nenhuma). Por predefinição, o índice é atualizado de forma síncrona em cada ação de inserção, substituição ou eliminação efetuada num documento na coleção. Esta atualização permite que as consultas honrem o mesmo nível de consistência que o do documento lê sem qualquer atraso para o índice recuperar.
Tipos de índice e precisão: o tipo ou esquema utilizado para entradas de índice tem um impacto direto no armazenamento e no desempenho do índice. Para um esquema com maior precisão, as consultas são normalmente mais rápidas. No entanto, também existe uma sobrecarga de armazenamento mais elevada para o índice. Escolher uma precisão mais baixa significa que mais documentos podem ter de ser processados durante a execução da consulta, mas a sobrecarga de armazenamento será mais baixa.
Caminhos de índice: nos documentos, pode escolher os caminhos que têm de ser incluídos ou excluídos da indexação, o que pode oferecer um desempenho de escrita melhorado e um armazenamento de índice mais baixo para cenários em que os padrões de consulta são conhecidos previamente.
As tabelas seguintes mostram alguns caminhos de indexação de exemplo e como são utilizados nas consultas.
| Propriedade | Descrição |
|---|---|
| /* | Caminho predefinido para a coleção. Recursivo e aplica-se a toda a árvore de documentos. |
| /prop/? | Caminho do índice necessário para servir consultas como as seguintes (com tipos de Hash ou Intervalo, respetivamente): 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/* | Caminho do índice para todos os caminhos na etiqueta especificada. Funciona com as seguintes 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/[]/? | Caminho do índice necessário para servir a iteração e as consultas JOIN em matrizes de escalares como ["a", "b", "c"]: Selecionar etiqueta FROM tag IN collection.props WHERE tag = "value" SELECT tag FROM collection c JOIN tag IN c.props WHERE tag > 5 |
| /props/[]/subprop/? | Caminho do índice necessário para servir a iteração e as consultas JOIN em matrizes 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/? | Caminho do índice necessário para servir consultas (com tipos de Hash ou Intervalo, respetivamente): 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 obter mais informações sobre as políticas de indexação do Cosmos DB, veja Políticas de indexação do Cosmos DB. Para efeitos da documentação da API REST, todos os exemplos utilizam a indexação automática.
Ofertas e Níveis de Desempenho
Quando uma coleção é criada, é também criado um recurso de Oferta que referencia a coleção criada. O recurso Oferta contém informações de configuração sobre o débito da coleção em unidades de pedido por segundo e unidades de pedido por minuto.
O nível de desempenho de uma coleção pode ser alterado com Substituir Oferta.
Tarefas
Pode fazer o seguinte com coleções de documentos: