$collStats (agregação)

Nesta página

Definição

Comportamento

Definição

$collStats

Novidade na versão 3.4.

Retorna estatísticas sobre uma coleção ou visualização.

O estágio $collStats tem o seguinte formato de protótipo:

{
  $collStats:
    {
      latencyStats: { histograms: <boolean> },
      storageStats: { scale: <number> },
      count: {},
      queryExecStats: {}
    }
}

O estágio $collStats aceita um documento de argumento com os seguintes campos opcionais:

Nome do campo	Descrição
`latencyStats`	Adiciona estatísticas de latência ao documento de retorno.
`latencyStats.histograms`	Adiciona informações de histograma de latência aos documentos incorporados em `latencyStats` se `true`.
`storageStats`	Adiciona estatísticas de armazenamento ao documento de retorno. Especifique um documento vazio (ou seja, `storageStats: {}`) para usar o fator de escala padrão de 1 para os vários dados de tamanho. O fator de escala de 1 exibe os tamanhos retornados em bytes. Especifique o fator de escala (ou seja, `storageStats: { scale: <number> }`) para utilizar o fator de escala especificado para os vários dados de tamanho. Por exemplo, para exibir kilobytes em vez de bytes, especifique um valor de escala de 1024. Se você especificar um fator de escala não inteiro, o MongoDB utilizará a parte inteira do fator especificado. Por exemplo, se você especificar um fator de escala de `1023.999`, MongoDB utilizará `1023` como o fator de escala. O fator de escala não afeta os tamanhos que especificam a unidade de medida no nome do campo, como `"bytes currently in the cache"`.
`count`	Adiciona o número total de documentos na collection ao documento de retorno. A contagem é baseada nos metadados da collection, que fornecem uma contagem rápida, mas às vezes imprecisa para clusters fragmentados. Consulte o campo`count` Novidade na versão 3.6.
`queryExecStats`	Adiciona estatísticas de execução da consulta ao documento de retorno.

Para uma collection em um conjunto de réplicas ou uma collection não fragmentada em um cluster, $collStats gera um único documento. Para uma collection fragmentada, $collStats gera um documento por shard. O documento de saída inclui os seguintes campos:

Nome do campo	Descrição
`ns`	O namespace da collection ou visualização solicitada.
`shard`	O nome do shard ao qual o documento de saída corresponde. Somente está presente quando `$collStats` executa em um cluster fragmentado. As collections fragmentadas e não fragmentadas produzirão este campo. Novidade na versão 3.6.
`host`	O nome do host e a porta do processo `mongod` que produziu o documento de saída. Novidade na versão 3.6.
`localTime`	A hora atual no servidor MongoDB, expressa em milissegundos UTC desde a época UNIX.
`latencyStats`	Estatísticas relacionadas à latência de solicitação de uma coleção ou visualização. Consulte Documento `latencyStats` para obter detalhes sobre esse documento. Presente somente quando a opção `latencyStats: {}` é especificada.
`storageStats`	Estatísticas relacionadas ao mecanismo de armazenamento de uma coleção. Consulte Documento `storageStats` para obter detalhes sobre esse documento. Os dados de vários tamanhos são dimensionados pelo fator especificado (com exceção dos tamanhos que especificam a unidade de medida no nome do campo). Presente somente quando a opção `storageStats` é especificada. Retorna um erro se aplicada a uma visualização.
`count`	O número total de documentos na collection. Estes dados também estão disponíveis em `storageStats.count`. A contagem é baseada nos metadados da collection, que fornecem uma contagem rápida, mas às vezes imprecisa para clusters fragmentados. Presente somente quando a opção `count: {}` é especificada.Retorna um erro se aplicada a uma visualização.
`queryExecStats`	Estatísticas relacionadas à execução da query para a collection. Presente somente quando a opção `queryExecStats: {}` é especificada.Retorna um erro se aplicada a uma visualização.

Comportamento

$collStats deve ser o primeiro estágio de um aggregation pipeline, senão o pipeline retorna um erro.

Transações

$collStats não é permitido em transações.

`latencyStats` Documento

O documento incorporado latencyStats só existe na saída caso você especifique a opção latencyStats.

Nome do campo	Descrição
`reads`	Estatísticas de latência para solicitações de leitura.
`writes`	Estatísticas de latência para solicitações de escrita.
`commands`	Estatísticas de latência para comandos de banco de dados.

Cada um desses campos contém um documento incorporado com os seguintes campos:

Nome do campo

Descrição

latency

Um número inteiro de 64 bits que informa o total de latência combinada em microssegundos.

ops

Um inteiro de 64 bits que informa o número total de operações realizadas na collection desde a inicialização.

histogram

Um array de documentos incorporados, cada um representando uma faixa de latência. Cada documento cobre o dobro da faixa do documento anterior. Para valores mais baixos entre 2048 microssegundos e aproximadamente 1 segundo, o histograma inclui meios-passos.

Este campo só existe com a opção latencyStats: { histograms: true }. Faixas vazias com count zero são omitidas da saída.

Cada documento contém os seguintes campos:

Nome do campo	Descrição
`micros`	Um número inteiro de 64bits que fornece o limite de tempo inferior inclusivo da faixa de latência atual em microssegundos. O intervalo do documento se estende entre o valor `micros` do documento anterior, exclusive, e o valor `micros` deste documento, inclusive.
`count`	Um número inteiro de 64 bits que informa o número de operações com latência inferior ou igual a `micros`.

Por exemplo, se collStats retornar o seguinte histograma:

histogram: [
  { micros: NumberLong(0), count: NumberLong(10) },
  { micros: NumberLong(2), count: NumberLong(1) },
  { micros: NumberLong(4096), count: NumberLong(1) },
  { micros: NumberLong(16384), count: NumberLong(1000) },
  { micros: NumberLong(49152), count: NumberLong(100) }
]

Isso indica que houve:

10 operações com 2 microssegundos ou menos
1 operação na faixa de [2, 4) microssegundos
1 operação na faixa de [4096, 6144) microssegundos
1000 operações no intervalo de [16384, 24576) microssegundos
100 operações no intervalo de [49152, 65536) microssegundos

[1]	A notação do símbolo `(` nesta página significa que o valor é exclusivo. A notação do símbolo `]` nesta página significa que o valor é inclusivo.

Por exemplo, se você executar $collStats com a opção latencyStats: {} em uma collection matrices:

db.matrices.aggregate( [ { $collStats: { latencyStats: { histograms: true } } } ] )

Esta query retornará um resultado semelhante ao seguinte:

{ "ns" : "test.matrices",
  "host" : "mongo.example.net:27017",
  "localTime" : ISODate("2017-10-06T19:43:56.599Z"),
  "latencyStats" :
    { "reads" :
        { "histogram" : [
            { "micros" : NumberLong(16),
              "count" : NumberLong(3) },
            { "micros" : NumberLong(32),
              "count" : NumberLong(1) },
            { "micros" : NumberLong(128),
              "count" : NumberLong(1) } ],
          "latency" : NumberLong(264),
          "ops" : NumberLong(5) },
      "writes" :
        { "histogram" : [
            { "micros" : NumberLong(32),
              "count" : NumberLong(1) },
            { "micros" : NumberLong(64),
              "count" : NumberLong(3) },
            { "micros" : NumberLong(24576),
              "count" : NumberLong(1) } ],
          "latency" : NumberLong(27659),
          "ops" : NumberLong(5) },
      "commands" :
        { "histogram" : [
            {
               "micros" : NumberLong(196608),
               "count" : NumberLong(1)
            }
          ],
          "latency" : NumberLong(0),
          "ops" : NumberLong(0) },
      "transactions" : {
         "histogram" : [ ],
         "latency" : NumberLong(0),
         "ops" : NumberLong(0)
      }
    }
}

`storageStats` Documento

O documento incorporado storageStats só existe na saída caso você especifique a opção storageStats.

O conteúdo deste documento depende do mecanismo de armazenamento em uso. Consulte Saída para obter uma referência sobre este documento.

Por exemplo, se você executar o $collStats com a opção storageStats: {} em uma collection matrices utilizando o Mecanismo de armazenamento WiredTiger:

db.matrices.aggregate( [ { $collStats: { storageStats: { } } } ] )

Esta query retornará um resultado semelhante ao seguinte:

{
  "ns" : "test.matrices",
  "host" : "mongo.example.net:27017",
  "localTime" : ISODate("2020-03-06T01:44:57.437Z"),
  "storageStats" : {
    "size" : 608500363,
    "count" : 1104369,
    "avgObjSize" : 550,
    "storageSize" : 352878592,
    "freeStorageSize" : 2490380,
    "capped" : false,
    "wiredTiger" : {
      ...
    },
    "nindexes" : 2,
    "indexDetails" : {
      ...
    },
    "indexBuilds" : [    // Starting in MongoDB 4.2
       "_id_1_abc_1"
    ],
    "totalIndexSize" : 260337664,
    "totalSize" : 613216256,
    "indexSizes" : {
      "_id_" : 9891840,
      "_id_1_abc_1" : 250445824
    },
    "scaleFactor" : 1    // Starting in MongoDB 4.2
  }
}

Consulte Saída para obter uma referência sobre este documento.

Observação

Índices em andamento

A partir do MongoDB 4.2, o storageStats retornado inclui informações sobre índices em construção. Para obter detalhes, consulte:

Executar $collStats com a opção storageStats em uma visualização resulta em um erro.

`count` Campo

Novidade na versão 3.6.

O campo count só existirá na saída se você especificar a opção count.

Por exemplo, se você executar $collStats com a opção count: {} em uma collection matrices:

db.matrices.aggregate( [ { $collStats: { count: { } } } ] )

A query retorna um resultado semelhante ao seguinte:

{
  "ns" : "test.matrices",
  "host" : "mongo.example.net:27017",
  "localTime" : ISODate("2017-10-06T19:43:56.599Z"),
  "count" : 1103869
}

Observação

A contagem é baseada nos metadados da collection, que fornecem uma contagem rápida, mas às vezes imprecisa para clusters fragmentados.

O número total de documentos na coleção também está disponível como storageStats.count quando storageStats: {} é especificado. Para obter mais informações, consulte o documento storageStats .

`queryExecStats` Documento

O documento incorporado queryExecStats só existe na saída caso você especifique a opção queryExecStats.

O campo collectionScans contém um documento incorporado com os seguintes campos:

Nome do campo	Descrição
`total`	Um inteiro de 64 bits que informa o número total de query que executaram uma varredura de collection. O total consiste em query que usaram e não usaram um cursor persistente.
`nonTailable`	Um inteiro de 64 bits que informa o número de queries que executaram uma varredura de collection que não usou um cursor tailable.

Por exemplo, se você executar $collStats com a opção queryExecStats: {} em uma collection matrices:

db.matrices.aggregate( [ { $collStats: { queryExecStats: { } } } ] )

A query retorna um resultado semelhante ao seguinte:

{
  "ns": "test.matrices",
  "host": "mongo.example.net:27017",
  "localTime": ISODate("2020-06-03T14:23:29.711Z"),
  "queryExecStats": {
      "collectionScans": {
          "total": NumberLong(33),
          "nonTailable": NumberLong(31)
      }
  }
}

`$collStats` em collections fragmentadas

$collStats gera um documento por fragmento quando executado em collections fragmentadas. Cada documento de saída contém um campo shard com o nome do fragmento ao qual o documento corresponde.

Por exemplo, se você executar $collStats em uma collection fragmentada com a opção count: {} em uma collection denominada matrices:

db.matrices.aggregate( [ { $collStats: { count: { } } } ] )

A query retorna um resultado semelhante ao seguinte:

{
  "ns" : "test.matrices",
  "shard" : "s1",
  "host" : "s1-mongo1.example.net:27017",
  "localTime" : ISODate("2017-10-06T15:14:21.258Z"),
  "count" : 661705
}
{
  "ns" : "test.matrices",
  "shard" : "s2",
  "host" : "s2-mongo1.example.net:27017",
  "localTime" : ISODate("2017-10-06T15:14:21.258Z"),
  "count" : 442164
}

Dica

Veja também:

Voltar

$changeStream

$count

Definição

Comportamento

Transações

latencyStats Documento

storageStats Documento

Observação

Índices em andamento

count Campo

Observação

queryExecStats Documento

$collStats em collections fragmentadas

Dica

Veja também:

`latencyStats` Documento

`storageStats` Documento

`count` Campo

`queryExecStats` Documento

`$collStats` em collections fragmentadas