Timestamp sbozzati

Se una raccolta contiene documenti con valori indicizzati sequenziali, Cloud Firestore limita la frequenza di scrittura a 500 scritture al secondo. Questa pagina descrive come partizionare un campo del documento per superare questo limite. Innanzitutto, definiamo cosa intendiamo per "campi indicizzati sequenziali" e chiariamo quando si applica questo limite.

Campi indicizzati sequenziali

"Campi indicizzati sequenziali" indica qualsiasi raccolta di documenti che contiene un campo indicizzato in modo monotono crescente o decrescente. In molti casi, questo significa un campo timestamp, ma qualsiasi valore di campo che aumenta o diminuisce monotonicamente può attivare il limite di scrittura di 500 scritture al secondo.

Ad esempio, il limite si applica a una raccolta di user documenti con campo indicizzato userid se l'app assegna valori userid come segue:

  • 1281, 1282, 1283, 1284, 1285, ...

D'altra parte, non tutti i campi timestamp attivano questo limite. Se un campo timestamp tiene traccia di valori distribuiti in modo casuale, il limite di scrittura non si applica. Non importa nemmeno il valore effettivo del campo, ma solo che il campo aumenti o diminuisca monotonicamente. Ad esempio, entrambi i seguenti insiemi di valori di campo in aumento monotono attivano il limite di scrittura:

  • 100000, 100001, 100002, 100003, ...
  • 0, 1, 2, 3, ...

Suddivisione di un campo timestamp

Supponiamo che la tua app utilizzi un campo timestamp in aumento monotono. Se la tua app non utilizza il campo timestamp in nessuna query, puoi rimuovere il limite di 500 scritture al secondo non indicizzando il campo timestamp. Se hai bisogno di un campo timestamp per le tue query, puoi aggirare il limite utilizzando timestamp suddivisi:

  1. Aggiungi un campo shard accanto al campo timestamp. Utilizza 1..n valori distinti per il campo shard. In questo modo, il limite di scrittura per la raccolta viene aumentato a 500*n, ma devi aggregare le query n.
  2. Aggiorna la logica di scrittura in modo da assegnare casualmente un valore shard a ogni documento.
  3. Aggiorna le query per aggregare i set di risultati suddivisi.
  4. Disattiva gli indici a campo singolo sia per il campo shard sia per il campo timestamp. Elimina gli indici compositi esistenti che contengono il campo timestamp.
  5. Crea nuovi indici composti per supportare le query aggiornate. L'ordine dei campi in un indice è importante e il campo shard deve precedere il campo timestamp. Qualsiasi indice che includa il campo timestamp deve includere anche il campo shard.

Devi implementare i timestamp suddivisi in shard solo nei casi d'uso con tassi di scrittura sostenuti superiori a 500 scritture al secondo. In caso contrario, si tratta di un'ottimizzazione prematura. Lo sharding di un campo timestamp rimuove la limitazione di 500 scritture al secondo, ma con il compromesso di dover eseguire aggregazioni di query lato client.

Gli esempi seguenti mostrano come partizionare un campo timestamp e come eseguire query su un set di risultati partizionato.

Modello dei dati e query di esempio

Ad esempio, immagina un'app per l'analisi quasi in tempo reale di strumenti finanziari come valute, azioni comuni ed ETF. Questa app scrive documenti in una raccolta instruments nel seguente modo:

Node.js
async function insertData() {
  const instruments = [
    {
      symbol: 'AAA',
      price: {
        currency: 'USD',
        micros: 34790000
      },
      exchange: 'EXCHG1',
      instrumentType: 'commonstock',
      timestamp: Timestamp.fromMillis(
          Date.parse('2019-01-01T13:45:23.010Z'))
    },
    {
      symbol: 'BBB',
      price: {
        currency: 'JPY',
        micros: 64272000000
      },
      exchange: 'EXCHG2',
      instrumentType: 'commonstock',
      timestamp: Timestamp.fromMillis(
          Date.parse('2019-01-01T13:45:23.101Z'))
    },
    {
      symbol: 'Index1 ETF',
      price: {
        currency: 'USD',
        micros: 473000000
      },
      exchange: 'EXCHG1',
      instrumentType: 'etf',
      timestamp: Timestamp.fromMillis(
          Date.parse('2019-01-01T13:45:23.001Z'))
    }
  ];

  const batch = fs.batch();
  for (const inst of instruments) {
    const ref = fs.collection('instruments').doc();
    batch.set(ref, inst);
  }

  await batch.commit();
}

nonShardedTimestamps.js

Questa app esegue le seguenti query e ordina in base al campo timestamp:

Node.js
function createQuery(fieldName, fieldOperator, fieldValue, limit = 5) {
  return fs.collection('instruments')
      .where(fieldName, fieldOperator, fieldValue)
      .orderBy('timestamp', 'desc')
      .limit(limit)
      .get();
}

function queryCommonStock() {
  return createQuery('instrumentType', '==', 'commonstock');
}

function queryExchange1Instruments() {
  return createQuery('exchange', '==', 'EXCHG1');
}

function queryUSDInstruments() {
  return createQuery('price.currency', '==', 'USD');
}

nonShardedTimestamps.js
 
insertData()
    .then(() => {
      const commonStock = queryCommonStock()
          .then(
              (docs) => {
                console.log('--- queryCommonStock: ');
                docs.forEach((doc) => {
                  console.log(`doc = ${util.inspect(doc.data(), {depth: 4})}`);
                });
              }
          );
      const exchange1Instruments = queryExchange1Instruments()
          .then(
              (docs) => {
                console.log('--- queryExchange1Instruments: ');
                docs.forEach((doc) => {
                  console.log(`doc = ${util.inspect(doc.data(), {depth: 4})}`);
                });
              }
          );
      const usdInstruments = queryUSDInstruments()
          .then(
              (docs) => {
                console.log('--- queryUSDInstruments: ');
                docs.forEach((doc) => {
                  console.log(`doc = ${util.inspect(doc.data(), {depth: 4})}`);
                });
              }
          );
      return Promise.all([commonStock, exchange1Instruments, usdInstruments]);
    });
nonShardedTimestamps.js

Dopo alcune ricerche, determini che l'app riceverà tra 1000 e 1500 aggiornamenti degli strumenti al secondo. Questo supera le 500 scritture al secondo consentite per le raccolte contenenti documenti con campi timestamp indicizzati. Per aumentare il throughput di scrittura, devi avere 3 valori di shard, MAX_INSTRUMENT_UPDATES/500 = 3. Questo esempio utilizza i valori di partizione x, y e z. Puoi anche utilizzare numeri o altri caratteri per i valori dello shard.

Aggiunta di un campo di partizionamento

Aggiungi un campo shard ai tuoi documenti. Imposta il campo shard sui valori x, y o z, il che aumenta il limite di scrittura nella raccolta a 1500 scritture al secondo.

Node.js
// Define our 'K' shard values
const shards = ['x', 'y', 'z'];
// Define a function to help 'chunk' our shards for use in queries.
// When using the 'in' query filter there is a max number of values that can be
// included in the value. If our number of shards is higher than that limit
// break down the shards into the fewest possible number of chunks.
function shardChunks() {
  const chunks = [];
  let start = 0;
  while (start < shards.length) {
    const elements = Math.min(MAX_IN_VALUES, shards.length - start);
    const end = start + elements;
    chunks.push(shards.slice(start, end));
    start = end;
  }
  return chunks;
}

// Add a convenience function to select a random shard
function randomShard() {
  return shards[Math.floor(Math.random() * Math.floor(shards.length))];
}

shardedTimestamps.js
 
async function insertData() {
  const instruments = [
    {
      shard: randomShard(),  // add the new shard field to the document
      symbol: 'AAA',
      price: {
        currency: 'USD',
        micros: 34790000
      },
      exchange: 'EXCHG1',
      instrumentType: 'commonstock',
      timestamp: Timestamp.fromMillis(
          Date.parse('2019-01-01T13:45:23.010Z'))
    },
    {
      shard: randomShard(),  // add the new shard field to the document
      symbol: 'BBB',
      price: {
        currency: 'JPY',
        micros: 64272000000
      },
      exchange: 'EXCHG2',
      instrumentType: 'commonstock',
      timestamp: Timestamp.fromMillis(
          Date.parse('2019-01-01T13:45:23.101Z'))
    },
    {
      shard: randomShard(),  // add the new shard field to the document
      symbol: 'Index1 ETF',
      price: {
        currency: 'USD',
        micros: 473000000
      },
      exchange: 'EXCHG1',
      instrumentType: 'etf',
      timestamp: Timestamp.fromMillis(
          Date.parse('2019-01-01T13:45:23.001Z'))
    }
  ];

  const batch = fs.batch();
  for (const inst of instruments) {
    const ref = fs.collection('instruments').doc();
    batch.set(ref, inst);
  }

  await batch.commit();
}

shardedTimestamps.js

Esecuzione di query sul timestamp sbozzato

L'aggiunta di un campo shard richiede l'aggiornamento delle query per aggregare i risultati suddivisi in shard:

Node.js
function createQuery(fieldName, fieldOperator, fieldValue, limit = 5) {
  // For each shard value, map it to a new query which adds an additional
  // where clause specifying the shard value.
  return Promise.all(shardChunks().map(shardChunk => {
        return fs.collection('instruments')
            .where('shard', 'in', shardChunk)  // new shard condition
            .where(fieldName, fieldOperator, fieldValue)
            .orderBy('timestamp', 'desc')
            .limit(limit)
            .get();
      }))
      // Now that we have a promise of multiple possible query results, we need
      // to merge the results from all of the queries into a single result set.
      .then((snapshots) => {
        // Create a new container for 'all' results
        const docs = [];
        snapshots.forEach((querySnapshot) => {
          querySnapshot.forEach((doc) => {
            // append each document to the new all container
            docs.push(doc);
          });
        });
        if (snapshots.length === 1) {
          // if only a single query was returned skip manual sorting as it is
          // taken care of by the backend.
          return docs;
        } else {
          // When multiple query results are returned we need to sort the
          // results after they have been concatenated.
          // 
          // since we're wanting the `limit` newest values, sort the array
          // descending and take the first `limit` values. By returning negated
          // values we can easily get a descending value.
          docs.sort((a, b) => {
            const aT = a.data().timestamp;
            const bT = b.data().timestamp;
            const secondsDiff = aT.seconds - bT.seconds;
            if (secondsDiff === 0) {
              return -(aT.nanoseconds - bT.nanoseconds);
            } else {
              return -secondsDiff;
            }
          });
          return docs.slice(0, limit);
        }
      });
}

function queryCommonStock() {
  return createQuery('instrumentType', '==', 'commonstock');
}

function queryExchange1Instruments() {
  return createQuery('exchange', '==', 'EXCHG1');
}

function queryUSDInstruments() {
  return createQuery('price.currency', '==', 'USD');
}

shardedTimestamps.js
 
insertData()
    .then(() => {
      const commonStock = queryCommonStock()
          .then(
              (docs) => {
                console.log('--- queryCommonStock: ');
                docs.forEach((doc) => {
                  console.log(`doc = ${util.inspect(doc.data(), {depth: 4})}`);
                });
              }
          );
      const exchange1Instruments = queryExchange1Instruments()
          .then(
              (docs) => {
                console.log('--- queryExchange1Instruments: ');
                docs.forEach((doc) => {
                  console.log(`doc = ${util.inspect(doc.data(), {depth: 4})}`);
                });
              }
          );
      const usdInstruments = queryUSDInstruments()
          .then(
              (docs) => {
                console.log('--- queryUSDInstruments: ');
                docs.forEach((doc) => {
                  console.log(`doc = ${util.inspect(doc.data(), {depth: 4})}`);
                });
              }
          );
      return Promise.all([commonStock, exchange1Instruments, usdInstruments]);
    });
shardedTimestamps.js

Aggiorna le definizioni degli indici

Per rimuovere il vincolo di 500 scritture al secondo, elimina gli indici a campo singolo e composti esistenti che utilizzano il campo timestamp.

Elimina le definizioni di indice composto

Console Firebase

  1. Apri la pagina Cloud Firestore Indici compositi nella console Firebase.

    Vai a Indici composti

  2. Per ogni indice che contiene il campo timestamp, fai clic sul pulsante e poi su Elimina.

Console di GCP

  1. Nella console Google Cloud, vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco.

  3. Nel menu di navigazione, fai clic su Indici, quindi sulla scheda Composito.

  4. Utilizza il campo Filtro per cercare le definizioni di indice che contengono il campo timestamp.

  5. Per ciascuno di questi indici, fai clic sul pulsante e poi su Elimina.

Interfaccia a riga di comando di Firebase

  1. Se non hai configurato l'interfaccia a riga di comando di Firebase, segui queste istruzioni per installare l'interfaccia a riga di comando ed eseguire il comando firebase init. Durante il comando init, assicurati di selezionare Firestore: Deploy rules and create indexes for Firestore.
  2. Durante la configurazione, l'interfaccia a riga di comando di Firebase scarica le definizioni di indice esistenti in un file denominato, per impostazione predefinita, firestore.indexes.json.

  3. Rimuovi tutte le definizioni di indice che contengono il campo timestamp, ad esempio:

    {
"indexes": [
  // Delete composite index definition that contain the timestamp field
  {
    "collectionGroup": "instruments",
    "queryScope": "COLLECTION",
    "fields": [
      {
        "fieldPath": "exchange",
        "order": "ASCENDING"
      },
      {
        "fieldPath": "timestamp",
        "order": "DESCENDING"
      }
    ]
  },
  {
    "collectionGroup": "instruments",
    "queryScope": "COLLECTION",
    "fields": [
      {
        "fieldPath": "instrumentType",
        "order": "ASCENDING"
      },
      {
        "fieldPath": "timestamp",
        "order": "DESCENDING"
      }
    ]
  },
  {
    "collectionGroup": "instruments",
    "queryScope": "COLLECTION",
    "fields": [
      {
        "fieldPath": "price.currency",
        "order": "ASCENDING"
      },
      {
        "fieldPath": "timestamp",
        "order": "DESCENDING"
      }
    ]
  },
 ]
}

  4. Esegui il deployment delle definizioni dell'indice aggiornate:

    firebase deploy --only firestore:indexes

Aggiornare le definizioni dell'indice a campo singolo

Console Firebase

  1. Apri la pagina Cloud Firestore Indici a campo singolo nella console Firebase.

    Vai a Indici a campo singolo

  2. Fai clic su Aggiungi esenzione.

  3. In ID raccolta, inserisci instruments. In Percorso campo, inserisci timestamp.

  4. In Ambito query, seleziona sia Raccolta sia Gruppo di raccolte.

  5. Fai clic su Avanti.

  6. Imposta tutte le impostazioni di indicizzazione su Disattivato. Fai clic su Salva.

  7. Ripeti gli stessi passaggi per il campo shard.

Console di GCP

  1. Nella console Google Cloud, vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco.

  3. Nel menu di navigazione, fai clic su Indici, quindi sulla scheda Singolo campo.

  4. Fai clic sulla scheda Campo singolo.

  5. Fai clic su Aggiungi esenzione.

  6. In ID raccolta, inserisci instruments. In Percorso campo, inserisci timestamp.

  7. In Ambito query, seleziona sia Raccolta sia Gruppo di raccolte.

  8. Fai clic su Avanti.

  9. Imposta tutte le impostazioni di indicizzazione su Disattivato. Fai clic su Salva.

  10. Ripeti gli stessi passaggi per il campo shard.

Interfaccia a riga di comando di Firebase

  1. Aggiungi quanto segue alla sezione fieldOverrides del file di definizioni dell'indice:

    {
 "fieldOverrides": [
   // Disable single-field indexing for the timestamp field
   {
     "collectionGroup": "instruments",
     "fieldPath": "timestamp",
     "indexes": []
   },
 ]
}

  2. Esegui il deployment delle definizioni dell'indice aggiornate:

    firebase deploy --only firestore:indexes

Crea nuovi indici composti

Dopo aver rimosso tutti gli indici precedenti contenenti timestamp, definisci i nuovi indici richiesti dalla tua app. Qualsiasi indice contenente il campo timestamp deve contenere anche il campo shard. Ad esempio, per supportare le query precedenti, aggiungi i seguenti indici:

Raccolta Campi indicizzati Ambito di query
strumentazioni shard, price.currency, timestamp Raccolta
strumentazioni shard, exchange, timestamp Raccolta
strumentazioni shard, instrumentType, timestamp Raccolta

Messaggi di errore

Puoi creare questi indici eseguendo le query aggiornate.

Ogni query restituisce un messaggio di errore con un link per creare l'indice richiesto nella console Firebase.

Interfaccia a riga di comando di Firebase

  1. Aggiungi i seguenti indici al file di definizione dell'indice:

     {
   "indexes": [
   // New indexes for sharded timestamps
     {
       "collectionGroup": "instruments",
       "queryScope": "COLLECTION",
       "fields": [
         {
           "fieldPath": "shard",
           "order": "DESCENDING"
         },
         {
           "fieldPath": "exchange",
           "order": "ASCENDING"
         },
         {
           "fieldPath": "timestamp",
           "order": "DESCENDING"
         }
       ]
     },
     {
       "collectionGroup": "instruments",
       "queryScope": "COLLECTION",
       "fields": [
         {
           "fieldPath": "shard",
           "order": "DESCENDING"
         },
         {
           "fieldPath": "instrumentType",
           "order": "ASCENDING"
         },
         {
           "fieldPath": "timestamp",
           "order": "DESCENDING"
         }
       ]
     },
     {
       "collectionGroup": "instruments",
       "queryScope": "COLLECTION",
       "fields": [
         {
           "fieldPath": "shard",
           "order": "DESCENDING"
         },
         {
           "fieldPath": "price.currency",
           "order": "ASCENDING"
         },
         {
           "fieldPath": "timestamp",
           "order": "DESCENDING"
         }
       ]
     },
   ]
 }

  2. Esegui il deployment delle definizioni dell'indice aggiornate:

    firebase deploy --only firestore:indexes

Informazioni sul limite di scrittura per i campi indicizzati sequenziali

Il limite alla frequenza di scrittura per i campi indicizzati sequenziali deriva dal modo in cui Cloud Firestore archivia i valori dell'indice e ridimensiona le scritture dell'indice. Per ogni scrittura dell'indice, Cloud Firestore definisce una voce chiave-valore che concatena il nome del documento e il valore di ogni campo indicizzato. Cloud Firestore organizza queste voci di indice in gruppi di dati chiamati tablet. Ogni server Cloud Firestore contiene uno o più tablet. Quando il carico di scrittura su un determinato tablet diventa troppo elevato, Cloud Firestore viene scalato orizzontalmente dividendo il tablet in tablet più piccoli e distribuendo i nuovi tablet su diversi server Cloud Firestore.

Cloud Firestore inserisce le voci di indice vicine lessicograficamente sullo stesso tablet. Se i valori dell'indice in una tabella sono troppo vicini tra loro, ad esempio per i campi timestamp, Cloud Firestore non può dividere in modo efficiente la tabella in tabelle più piccole. In questo modo si crea un hotspot in cui un singolo tablet riceve troppo traffico e le operazioni di lettura e scrittura nell'hotspot diventano più lente.

Se suddividi un campo timestamp, consenti a Cloud Firestore di dividere in modo efficiente i workload su più tablet. Anche se i valori del campo timestamp potrebbero rimanere vicini tra loro, il valore concatenato di shard e indice offre Cloud Firestore spazio sufficiente tra le voci dell'indice per suddividerle tra più tablet.

Passaggi successivi