Coleções

  • Artigo

O Azure Cosmos DB é um banco de dados multimodelo distribuído globalmente que dá suporte aos modelos de dados de documento, grafo e chave-valor. O conteúdo nesta seção destina-se à criação, consulta e gerenciamento de recursos de coleta usando a API do SQL por meio do REST.

A API REST dá suporte a operações CRUD básicas nos recursos em uma conta de banco de dados. Uma coleção é um contêiner de documentos JSON e lógica do aplicativo JavaScript associada, ou seja, procedimentos armazenados, disparadores e funções definidas pelo usuário. Este tópico descreve as operações REST usadas para gerenciar coleções de documentos.

Observação

Esses artigos de referência de API mostram como criar recursos usando a API do plano de dados do Azure Cosmos DB. Com a API do plano de dados, você pode configurar opções básicas, como a política de indexação, chaves de partição como você pode com SDKs do Cosmos DB. Se você precisar de suporte completo para todos os recursos do Azure Cosmos DB, recomendamos usar o Provedor de Recursos do Cosmos DB.

Uma coleção é mapeada para um contêiner no Azure Cosmos DB. Portanto, é uma entidade faturável, em que o custo é determinado pela taxa de transferência provisionada expressa em unidades de solicitação por segundo. As coleções podem abranger uma ou mais partições/servidores e escalar e reduzir verticalmente em termos de taxa de transferência. As coleções são particionadas automaticamente em um ou mais servidores físicos pelo Azure Cosmos DB.

Uma vez que uma coleção é um recurso do sistema, ela tem um esquema fixo. O caminho de URI de uma coleção é representado por colls no modelo de recurso.

O exemplo a seguir 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 configurações de política de indexação para coleção.
partitionKey São as configurações de particionamento da coleção.
_Livrar É 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. É usada internamente para posicionamento 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.
_Auto É uma propriedade gerada pelo sistema. É o URI endereçável exclusivo do recurso.
_Etag É uma propriedade gerada pelo sistema que representa a etag de recurso necessária para o controle 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).
_Gatilhos É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso de gatilhos.
_Udfs É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso udfs (funções definidas pelo usuário).
_Conflitos É uma propriedade gerada pelo sistema que especifica o caminho endereçável do recurso de conflitos. Durante uma operação em um recurso dentro de uma coleção, se ocorrer um conflito, os usuários podem inspecionar os recursos conflitantes executando 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 padrão é True, portanto, todos os documentos são indexados. Definir o valor como False permitiria a configuração manual de caminhos de indexação.
indexingMode Por padrão, o modo de indexação é Consistente. Isso significa que a indexação ocorre de forma síncrona durante a inserção, substituição ou exclusão de documentos. Para que a indexação ocorra de modo assíncrono, defina o modo de indexação para lento.
includedPaths A matriz que contém os caminhos dos documentos a serem indexados. Por padrão, dois caminhos são incluídos: o caminho/, que especifica que todos os caminhos do documento sejam indexados e o caminho _ts, que indexa para uma comparação de intervalo de carimbo de data/hora.
excludedPaths A matriz que contém os caminhos de documento a serem excluídos da indexação.

Propriedades em Caminhos Incluídos

Propriedade Descrição
path Caminho ao qual o comportamento de indexação se aplica. Caminhos de índice começam com a raiz (/) e geralmente terminam com o operador de curinga ?, indicando que há vários valores possíveis para o prefixo. Por exemplo, para servir SELECT * FROM Families F WHERE F.familyName = "Andersen", você deve incluir um caminho de índice para /familyName/? na política de índice da coleção.

Os caminhos de índice também podem usar o operador curinga * para especificar o comportamento de caminhos recursivamente no prefixo. Por exemplo, /payload/* pode ser usado para incluir tudo na propriedade payload da indexação.
dataType É o tipo de dados ao qual o comportamento de indexação é aplicado. Pode ser String, Number, Point, Polygon ou LineString. Boolianos e nulos são indexados automaticamente
kind O tipo do índice. Índices de hash são úteis para comparações de igualdade, enquanto índices range são úteis para igualdade, comparações de intervalo e classificação. Í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 de Caracteres. Não aplicável aos tipos de dados Point, Polygon e LineString .

Propriedades em Caminhos Excluídos

Propriedade Descrição
path Caminho excluído da indexação. Os caminhos de índice começam com a raiz (/) e normalmente terminam com o operador * curinga.. Por exemplo, /payload/* pode ser usado para excluir tudo na propriedade de conteúdo da indexação.

Propriedades em Chave de Partição

Propriedade Descrição
path Uma matriz de caminhos usando quais dados dentro da coleção podem ser particionados. Os caminhos não devem conter um curinga ou uma barra à direita. Por exemplo, a propriedade JSON "AccountNumber" é especificada como "/AccountNumber". A matriz deve conter apenas um único valor.
kind O algoritmo usado para particionamento. Há suporte apenas para Hash .

Política de indexação

À medida que os documentos são adicionados a uma coleção, o Cosmos DB, por padrão, indexa automaticamente os documentos, permitindo que os documentos sejam consultados. É no nível de coleção que você configura a política de indexação. Uma vez que a política de indexação está definida no nível de coleção, cada coleção dentro de um banco de dados pode ter diferentes políticas de indexação.

A política de indexação para uma coleção pode especificar as seguintes opções:

  • Automático: você pode escolher se deseja que a coleção indexe automaticamente todos os documentos ou não. Por padrão, todos os documentos são indexados automaticamente, mas você pode optar por desativá-lo. Quando a indexação estiver desativada, documentos podem ser acessados somente por meio de seus self links ou através de consultas usando um ID.

  • Modo de Indexação: você pode escolher entre atualizações de índice síncronas (consistentes), assíncronas (lentas) e nenhuma indexação (Nenhuma). Por padrão, o índice é atualizado de forma síncrona em cada ação de inserção, substituição ou exclusão executada em um documento na coleção. Essa atualização permite que as consultas cumpram o mesmo nível de consistência que o do documento lê sem nenhum atraso para que o índice seja atualizado.

  • Tipos de índice e precisão: o tipo ou esquema usado para entradas de índice tem um impacto direto no armazenamento e no desempenho do índice. Para um esquema com maior precisão, as consultas geralmente são mais rápidas. No entanto, há também uma maior sobrecarga de armazenamento para o índice. Escolher uma precisão menor significa que pode ser preciso processar mais documentos durante a execução da consulta, mas a sobrecarga de armazenamento é menor.

  • Caminhos de índice: dentro de documentos, você pode escolher quais caminhos devem ser incluídos ou excluídos da indexação, o que pode oferecer melhor desempenho de gravação e menor armazenamento de índice para cenários em que os padrões de consulta são conhecidos com antecedência.

As tabelas a seguir mostram alguns caminhos de indexação de exemplo e como eles são usados nas consultas.

Propriedade Descrição
/* Caminho padrão para coleta. Recursiva e aplica-se em toda árvore do documento inteiro.
/prop/? Caminho de índice necessário para fazer consultas como as seguintes (com tipos hash e 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/* Caminho de índice para todos os caminhos sob o rótulo especificado. 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 de índice necessário para atender consultas de iteração e JOIN em matrizes 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/? Caminho de índice necessário para atender consultas de iteração e 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 de índice necessário para fazer consultas (com tipos hash e 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 obter mais informações sobre políticas de indexação do Cosmos DB, consulte Políticas de indexação do Cosmos DB. Para a finalidade da documentação API REST, todos os exemplos usam a indexação automática.

Ofertas e níveis de desempenho

Quando uma coleção é criada, um recurso offer também é criado que faz referência à coleção criada. O recurso Oferta contém informações de configuração sobre a taxa de transferência da coleção em unidades de solicitação por segundo e unidades de solicitação por minuto.

O nível de desempenho de uma coleção pode ser alterado usando Substituir Oferta.

Tarefas

Você pode fazer o seguinte com coleções de documentos: