Raccolte

  • Articolo

Azure Cosmos DB è un database multimodello distribuito a livello globale che supporta i modelli di dati document, graph e key-value. Il contenuto di questa sezione consiste nel creare, eseguire query e gestire le risorse della raccolta usando l'API SQL tramite REST.

L'API REST supporta operazioni CRUD di base sulle risorse in un account di database. Una raccolta è un contenitore di documenti JSON e della logica dell'applicazione JavaScript associata, ovvero stored procedure, trigger e funzioni definite dall'utente. In questo argomento vengono illustrate le operazioni REST usate per gestire le raccolte documenti.

Nota

Questi articoli di riferimento sulle API illustrano come creare risorse usando l'API del piano dati di Azure Cosmos DB. Con l'API del piano dati è possibile configurare opzioni di base, ad esempio criteri di indicizzazione, chiavi di partizione molto simili a quelle che è possibile usare gli SDK di Cosmos DB. Se è necessario il supporto completo delle funzionalità per tutte le risorse di Azure Cosmos DB, è consigliabile usare il provider di risorse Cosmos DB.

Una raccolta esegue il mapping a un contenitore in Azure Cosmos DB. Pertanto, è un'entità fatturabile, in cui il costo è determinato dalla velocità effettiva di cui è stato effettuato il provisioning espresso nelle unità di richiesta al secondo. Le raccolte possono estendersi su una o più partizioni/server e aumentare e ridurre in termini di velocità effettiva. Le raccolte vengono partizionate automaticamente in uno o più server fisici da Azure Cosmos DB.

Poiché una raccolta è una risorsa di sistema, ha uno schema fisso. Il percorso URI di una raccolta è rappresentato da colls nel modello di risorsa.

Nell'esempio seguente viene illustrata la definizione JSON di una raccolta:

{  
  "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/"  
}
Proprietà Descrizione
id È il nome univoco che identifica la nuova raccolta.
indexingPolicy Si tratta delle impostazioni dei criteri di indicizzazione per la raccolta.
partitionKey Si tratta delle impostazioni di configurazione del partizionamento per la raccolta.
_rid Si tratta di una proprietà generata dal sistema. L'ID risorsa (_rid) è un identificatore univoco che è anche gerarchico per ogni stack di risorse nel modello di risorsa. Viene usato internamente per il posizionamento e l'esplorazione della risorsa di autorizzazione.
_Ts Si tratta di una proprietà generata dal sistema. Indica il timestamp dell'ultimo aggiornamento della risorsa. Il valore è un timestamp.
_stesso Si tratta di una proprietà generata dal sistema. URI indirizzabile univoco per la risorsa.
_Etag Si tratta di una proprietà generata dal sistema che rappresenta l'etag della risorsa necessaria per il controllo di concorrenza ottimistica.
_Doc Si tratta di una proprietà generata dal sistema che specifica il percorso indirizzabile della risorsa documenti.
_sprocs Si tratta di una proprietà generata dal sistema che specifica il percorso indirizzabile della risorsa stored procedure (sprocs).
_Trigger Si tratta di una proprietà generata dal sistema che specifica il percorso indirizzabile della risorsa trigger.
_udfs Si tratta di una proprietà generata dal sistema che specifica il percorso indirizzabile della risorsa delle funzioni definite dall'utente .
_Conflitti Si tratta di una proprietà generata dal sistema che specifica il percorso indirizzabile della risorsa dei conflitti. Se durante un'operazione su una risorsa all'interno di una raccolta si verifica un conflitto, gli utenti possono controllare le risorse in conflitto eseguendo un'operazione GET sul percorso URI dei conflitti.

Proprietà in Criteri di indicizzazione

Proprietà Descrizione
Automatico Indica se l'indicizzazione automatica è attiva o disattiva. Il valore predefinito è True, quindi tutti i documenti vengono indicizzati. L'impostazione del valore su False consente la configurazione manuale dei percorsi di indicizzazione.
indexingMode Per impostazione predefinita, la modalità di indicizzazione è Coerente. Ciò significa che l'indicizzazione si verifica in modo sincrono durante l'inserimento, la sostituzione o l'eliminazione di documenti. Perché l'indicizzazione venga eseguita in modo asincrono, impostarne la modalità su lazy.
includedPaths Matrice che contiene i percorsi dei documenti da indicizzare. Per impostazione predefinita, sono inclusi due percorsi: /path, che specifica che tutti i percorsi del documento vengono indicizzati e il percorso _ts, che indicizza un confronto di intervallo timestamp.
esclusiPath Matrice che contiene i percorsi dei documenti da escludere dall'indicizzazione.

Proprietà in Percorsi inclusi

Proprietà Descrizione
path Percorso a cui si applica il comportamento di indicizzazione. I percorsi di indice iniziano con la radice (/) e terminano in genere con il carattere jolly ?, che indica la possibilità di molteplici valori per il prefisso. Ad esempio, per usare SELECT * FROM Families F WHERE F.familyName = "Andersen", è necessario includere un percorso di indice per /"familyName"/? nei criteri di indicizzazione della raccolta.

I percorsi di indice possono anche usare il carattere jolly * per specificare un comportamento ricorsivo dei percorsi al di sotto del prefisso. Ad esempio, è possibile usare /payload/* per includere tutti gli elementi nella proprietà payload dall'indicizzazione.
dataType È il tipo di dati a cui viene applicato il comportamento di indicizzazione. Può essere String, Number, Point, Polygon o LineString. I booleani e i valori Null vengono indicizzati automaticamente
gentile Tipo di indice. Gli indici hash sono utili per i confronti di uguaglianza mentre gli indici Range sono utili per l'uguaglianza, i confronti tra intervalli e l'ordinamento. Gli indici spaziali sono utili per le query spaziali.
precisione Precisione dell'indice. Può essere impostato su -1 per la precisione massima o tra 1-8 per Number e 1-100 per String. Non applicabile per i tipi di dati Point, Polygon e LineString .

Proprietà in Percorsi esclusi

Proprietà Descrizione
path Percorso escluso dall'indicizzazione. I percorsi di indice iniziano con la radice (/) e in genere terminano con l'operatore jolly *. È ad esempio possibile usare /payload/* per escludere dall'indicizzazione qualsiasi elemento al di sotto della proprietà payload.

Proprietà in Chiave di partizione

Proprietà Descrizione
path Matrice di percorsi che usano i dati all'interno della raccolta che possono essere partizionati. I percorsi non devono contenere un carattere jolly o una barra finale. Ad esempio, la proprietà JSON "AccountNumber" viene specificata come "/AccountNumber". La matrice deve contenere solo un singolo valore.
gentile Algoritmo utilizzato per il partizionamento. È supportato solo hash .

Criterio di indicizzazione

Man mano che i documenti vengono aggiunti a una raccolta, Cosmos DB per impostazione predefinita indicizza automaticamente i documenti, consentendo così di eseguire query sui documenti. I criteri di indicizzazione vengono configurati a livello di raccolta. Poiché i criteri di indicizzazione vengono impostati a livello di raccolta, ogni raccolta all'interno di un database può avere criteri di indicizzazione diversi.

I criteri di indicizzazione per una raccolta possono specificare le opzioni seguenti:

  • Automatico: è possibile scegliere se si desidera che la raccolta indicizza automaticamente tutti i documenti o meno. Per impostazione predefinita, tutti i documenti vengono indicizzati automaticamente, ma è possibile scegliere di disattivare tale funzionalità. Quando l'indicizzazione è disattivata, i documenti sono accessibili solo tramite i relativi self link o le query con ID.

  • Modalità di indicizzazione: è possibile scegliere tra gli aggiornamenti sincroni (coerenti), asincroni (lazy) e nessuna indicizzazione (Nessuno). Per impostazione predefinita, l'indice viene aggiornato in modo sincrono in ogni azione di inserimento, sostituzione o eliminazione eseguita su un documento della raccolta. Questo aggiornamento consente alle query di rispettare lo stesso livello di coerenza di quello del documento letto senza alcun ritardo per il recupero dell'indice.

  • Tipi di indice e precisione: il tipo o lo schema usato per le voci di indice ha un impatto diretto sull'archiviazione e sulle prestazioni dell'indice. Per uno schema con precisione più elevata, le query sono in genere più veloci, ma i costi di archiviazione dell'indice sono maggiori. Se si sceglie una precisione inferiore, è possibile che debbano essere elaborati più documenti durante l'esecuzione di query, ma i costi di archiviazione saranno inferiori.

  • Percorsi di indice: all'interno dei documenti è possibile scegliere quali percorsi devono essere inclusi o esclusi dall'indicizzazione, che possono offrire prestazioni di scrittura migliorate e una minore archiviazione degli indici per gli scenari in cui i modelli di query sono noti in precedenza.

Le tabelle seguenti mostrano alcuni percorsi di indicizzazione di esempio e il modo in cui vengono usati all'interno delle query.

Proprietà Descrizione
/* Percorso predefinito per la raccolta. Ricorsivo e applicabile all'intera struttura ad albero del documento.
/prop/? Percorso di indice che consente di servire query come le seguenti (rispettivamente con i tipi Hash e Range):

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/* Percorso di indice per tutti i percorsi al di sotto dell'etichetta specificata. Funziona con le query seguenti:

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/[]/? Percorso di indice necessario per gestire l'iterazione e le query JOIN su matrici di scalari come

["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/? Percorso di indice necessario per gestire l'iterazione e le query JOIN su matrici di oggetti come

[{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/? Percorso di indice che consente di servire query come le seguenti (rispettivamente con i tipi Hash e Range):

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

Per altre informazioni sui criteri di indicizzazione di Cosmos DB, vedere Criteri di indicizzazione di Cosmos DB. Ai fini della documentazione dell'API REST, tutti gli esempi usano l'indicizzazione automatica.

Offerte e livelli di prestazioni

Quando viene creata una raccolta, viene creata anche una risorsa Offer che fa riferimento alla raccolta creata. La risorsa Offerta contiene informazioni di configurazione sulla velocità effettiva della raccolta in unità richiesta al secondo e unità richiesta al minuto.

Il livello di prestazioni di una raccolta può essere modificato usando Sostituisci offerta.

Attività

È possibile eseguire le operazioni seguenti con le raccolte documenti: