Menu Docs

$out

$out usa documentos retornados pela pipeline de agregação e os grava em uma coleção especificada. O operador $out deve ser o último estágio no pipeline de agregação. No Atlas Data Federation, você pode usar $out para gravar dados de qualquer um dos armazenamentos de instância do banco de dados federadocompatíveis ou de vários armazenamentos de instância do banco de dados federado compatíveis ao usar consultas federadas para qualquer um dos seguintes:

  • Namespacedo Atlas cluster

  • AWS Buckets S3 com permissões de leitura e gravação

  • Contêineres de armazenamento de blob do Azure com permissões de leitura e gravação

Você deve se conectar à instância do seu banco de dados federado para usar $out.

É necessário ter:

  • Uma instância do banco de dados federado configurada para um bucket do S3 com permissões de leitura e gravação ou permissões s3:PutObject.

  • Um usuário do MongoDB com a função atlasAdmin ou uma função personalizada com o privilégio outToS3 .

É necessário ter:

  • Uma instância do banco de dados federado configurada para o Azure Blob Storage com uma função do Azure que tenha permissões de leitura e gravação.

  • Um usuário do MongoDB com a função atlasAdmin ou uma função personalizada com o privilégio outToAzure .

É necessário ter:

  • Uma instância do banco de dados federado configurada para um bucket do Google Cloud Storage com acesso a uma conta de serviço do GCP.

  • Um usuário do MongoDB com a função atlasAdmin ou uma função personalizada com o privilégio outToGCP .

Observação

Para usar $out para gravar em uma coleção em um banco de dados diferente no mesmo Atlas cluster, seu Atlas cluster deve estar na versão 5.0 do MongoDB ou posterior.

Você deve ser um usuário de banco de dados com uma das seguintes funções:

1{
2 "$out": {
3 "s3": {
4 "bucket": "<bucket-name>",
5 "region": "<aws-region>",
6 "filename": "<file-name>",
7 "format": {
8 "name": "<file-format>",
9 "maxFileSize": "<file-size>",
10 "maxRowGroupSize": "<row-group-size>",
11 "columnCompression": "<compression-type>"
12 },
13 "errorMode": "stop"|"continue"
14 }
15 }
16}
1{
2 "$out": {
3 "azure": {
4 "serviceURL": "<storage-account-url>",
5 "containerName": "<container-name>",
6 "region": "<azure-region>",
7 "filename": "<file-name>",
8 "format": {
9 "name": "<file-format>",
10 "maxFileSize": "<file-size>",
11 "maxRowGroupSize": "<row-group-size>",
12 "columnCompression": "<compression-type>"
13 },
14 "errorMode": "stop"|"continue"
15 }
16 }
17}
1{
2 "$out": {
3 "gcs": {
4 "bucket": "<bucket-name>",
5 "region": "<aws-region>",
6 "filename": "<file-name>",
7 "format": {
8 "name": "<file-format>",
9 "maxFileSize": "<file-size>",
10 "maxRowGroupSize": "<row-group-size>",
11 "columnCompression": "<compression-type>"
12 },
13 "errorMode": "stop"|"continue"
14 }
15 }
16}
1{
2 "$out": {
3 "atlas": {
4 "projectId": "<atlas-project-ID>",
5 "clusterName": "<atlas-cluster-name>",
6 "db": "<atlas-database-name>",
7 "coll": "<atlas-collection-name>"
8 }
9 }
10}
Campo
Tipo
Descrição
necessidade

s3

objeto

Local para gravar os documentos a partir da aggregation pipeline.

Obrigatório

s3.bucket

string

Nome do contêiner S3 para gravar os documentos do pipeline de agregação.

A chamada gerada para S3 insere um / entre s3.bucket e s3.filename. Não acrescente um / à sua string s3.bucket.

Por exemplo, se você definir s3.bucket como myBucket e s3.filename como myPath/myData, o Atlas Data Federation gravará o local de saída da seguinte forma:

s3://myBucket/myPath/myData.[n].json

Obrigatório

s3.region

string

Nome da região AWS na qual o bucket está hospedado. Se omitido, usa a configuração da instância do banco de dados federado para determinar a região em que o s3.bucket especificado está hospedado.

Opcional

s3.filename

string

Nome do arquivo em que os documentos da agregação pipeline serão gravados. O nome do arquivo pode ser constante ou criado dinamicamente a partir dos campos nos documentos que atingem o estágio $out. Qualquer expressão de nome de arquivo fornecida deve ser avaliada como um tipo de dados string.

IMPORTANTE: se houver arquivos em S3 com o mesmo nome e caminho dos arquivos recém-gerados, $out substituirá os arquivos existentes com os arquivos recém-gerados.

A chamada gerada para S3 insere um / entre s3.bucket e s3.filename. Não acrescente um / à sua string s3.filename.

Por exemplo, se você definir s3.filename como myPath/myData e s3.bucket como myBucket, o Atlas Data Federation gravará o local de saída da seguinte forma:

s3://myBucket/myPath/myData.[n].json

Obrigatório

s3.format

objeto

Detalhes do arquivo em S3.

Obrigatório

s3
.format
.name

enum

Formato do arquivo em S3. O valor pode ser um dos seguintes:

  • bson

  • bson.gz

  • csv

  • csv.gz

  • json 1

  • json.gz 1

  • parquet

  • tsv

  • tsv.gz

1 Para este formato, $out grava dados no formato JSON estendido do MongoDB .

Para saber mais, consulte Limitações.

Obrigatório

s3
.format
.maxFileSize

bytes

Tamanho máximo do arquivo BSON descompactado em S3. Ao converter de BSON para o formato de sua preferência, o arquivo de saída resultante pode ser menor (por exemplo, ao converter para Parquet) ou maior (por exemplo, ao converter para CSV).

Se um documento for maior que o maxFileSize, o Atlas Data Federation gravará o documento como um arquivo próprio. Os seguintes sufixos são aceitos:

Base 10: dimensionamento em múltiplos de 1.000

  • B

  • KB

  • MB

  • GB

  • TB

  • PB

Base 2: dimensionamento em múltiplos de 1.024

  • KiB

  • MiB

  • GiB

  • TiB

  • PiB

Se omitido, o padrão é 200MiB.

Quando o limite de tamanho do arquivo atual é atingido, a Atlas Data Federation cria um novo arquivo em S3. Ele anexa um 1 antes da extensão do nome do arquivo para o primeiro arquivo. Para cada arquivo subsequente, o Atlas Data Federation aumenta o número anexado por um.

Por exemplo, <filename>.1.<fileformat> e <filename>.2.<fileformat>.

Opcional

s3
.format
.maxRowGroupSize

string

Compatível apenas com o formato de arquivo Parquet.

Tamanho máximo do grupo de linhas a ser usado ao gravar no arquivo Parquet. Se omitido, o padrão será 128 MiB ou o valor do s3.format.maxFileSize, o que for menor. O valor máximo permitido é 1 GB.

Opcional

s3
.format
.columnCompression

string

Compatível apenas com o formato de arquivo Parquet.

Tipo de compressão para aplicar para comprimir dados dentro de um arquivo Parquet ao formatar o arquivo Parquet. Os valores válidos são:

  • gzip

  • snappy

  • uncompressed

Se omitido, o padrão é snappy.

Para saber mais, consulte Formatos de dados compatíveis.

Opcional

errorMode

enum

Especifica como o Atlas Data Federation deve proceder se houver erros ao processar um documento. Por exemplo, se o Atlas Data Federation encontrar uma array em um documento quando o Atlas Data Federation estiver gravando em um arquivo CSV, o Atlas Data Federation utilizará este valor para determinar se deseja ou não ignorar o documento e processar outros documentos. Os valores válidos são:

  • continue para ignorar o documento e continuar processando os documentos restantes. O Atlas Data Federation também grava o documento que causou o erro em um arquivo de erro.

    Para saber mais, consulteErros.

  • stop para parar nesse ponto e não processar os documentos restantes.

Se omitido, o padrão é continue.

Opcional

Campo
Tipo
Descrição
necessidade

azure

objeto

Local para gravar os documentos a partir da aggregation pipeline.

Obrigatório

azure.serviceURL

string

URL da conta de armazenamento Azure na qual gravar documentos do pipeline de agregação.

Obrigatório

azure.containerName

string

Nome do contêiner Azure Blob Storage no qual gravar documentos do pipeline de agregação.

Obrigatório

azure.region

string

Nome da região do Azure que hospeda o contêiner Blob Storage.

Obrigatório

azure.filename

string

Nome do arquivo no qual gravar os documentos do pipeline de agregação.

Aceita valor constante ou valores que avaliam para string criados dinamicamente a partir dos campos nos documentos que chegam ao estágio $out. Se houver arquivos no Azure Blob Storage com o mesmo nome e caminho dos arquivos recém-gerados, $out substituirá os arquivos existentes pelos arquivos recém-gerados.

Obrigatório

azure.format

objeto

Detalhes do arquivo no Armazenamento de Blobs do Azure .

Obrigatório

azure
.format
.name

enum

Formato do arquivo no Azure Blob Storage. O valor pode ser um dos seguintes:

  • bson

  • bson.gz

  • csv

  • csv.gz

  • json 1

  • json.gz 1

  • parquet

  • tsv

  • tsv.gz

1 Para este formato, $out grava dados no formato JSON estendido do MongoDB .

Para saber mais, consulte Limitações.

Obrigatório

azure
.format
.maxFileSize

bytes

Tamanho máximo do documento BSON descompactado no Azure Blob Storage. Ao converter de BSON para o formato de sua preferência, o arquivo de saída resultante pode ser menor (por exemplo, ao converter para Parquet) ou maior (por exemplo, ao converter para CSV).

Se um documento for maior que o maxFileSize, o Atlas Data Federation gravará o documento como um arquivo próprio. Os seguintes sufixos são aceitos:

Base 10: dimensionamento em múltiplos de 1.000

  • B

  • KB

  • MB

  • GB

  • TB

  • PB

Base 2: dimensionamento em múltiplos de 1.024

  • KiB

  • MiB

  • GiB

  • TiB

  • PiB

Se omitido, o padrão é 200MiB.

Quando o limite de tamanho do arquivo atual é atingido, a Atlas Data Federation cria um novo arquivo em S3. Ele anexa um 1 antes da extensão do nome do arquivo para o primeiro arquivo. Para cada arquivo subsequente, o Atlas Data Federation aumenta o número anexado por um.

Por exemplo, <filename>.1.<fileformat> e <filename>.2.<fileformat>.

Opcional

azure
.format
.maxRowGroupSize

string

Compatível apenas com o formato de arquivo Parquet.

Tamanho máximo do grupo de linhas a ser usado ao gravar no arquivo Parquet. Se omitido, o padrão será 128 MiB ou o valor do azure.format.maxFileSize, o que for menor. O valor máximo permitido é 1 GB.

Opcional

azure
.format
.columnCompression

string

Compatível apenas com o formato de arquivo Parquet.

Tipo de compressão para aplicar para comprimir dados dentro de um arquivo Parquet ao formatar o arquivo Parquet. Os valores válidos são:

  • gzip

  • snappy

  • uncompressed

Se omitido, o padrão é snappy.

Para saber mais, consulte Formatos de dados compatíveis.

Opcional

errorMode

enum

Especifica como o Atlas Data Federation deve proceder quando encontrar um erro ao processar um documento. Os valores válidos são:

  • continue para ignorar o documento e continuar processando os documentos restantes. O Atlas Data Federation registra o erro em um arquivo de erro.

  • stop para parar sem processar os documentos restantes. O Atlas Data Federation registra o erro em um arquivo de erro.

Se omitido, o padrão é continue.

Para saber mais,consulte Erros.

Opcional

Campo
Tipo
Descrição
necessidade

gcs

objeto

Local para gravar os documentos a partir da aggregation pipeline.

Obrigatório

gcs.bucket

string

Nome do contêiner do Google Cloud Storage para gravar os documentos do pipeline de agregação.

A chamada gerada para o Google Cloud insere um / entre gcs.bucket e gcs.filename. Não acrescente um / à sua string gcs.bucket.

Por exemplo, se você definir gcs.bucket como myBucket e gcs.filename como myPath/myData, o Atlas Data Federation gravará o local de saída da seguinte forma:

gcs://myBucket/myPath/myData.[n].json

Obrigatório

gcs.region

string

Nome da região AWS na qual o bucket está hospedado. Se omitido, usa a configuração da instância do banco de dados federado para determinar a região em que o gcs.bucket especificado está hospedado.

Opcional

gcs.filename

string

Nome do arquivo em que os documentos da agregação pipeline serão gravados. O nome do arquivo pode ser constante ou criado dinamicamente a partir dos campos nos documentos que atingem o estágio $out. Qualquer expressão de nome de arquivo fornecida deve ser avaliada como um tipo de dados string. Se houver arquivos no Google Cloud Platform Storage com o mesmo nome e caminho dos arquivos recém-gerados, $out substituirá os arquivos existentes pelos arquivos recém-gerados.

A chamada gerada para o Google Cloud Storage insere um / entre gcs.bucket e gcs.filename. Não anexar um / à string gcs.filename.

Por exemplo, se você definir gcs.filename como myPath/myData e gcs.bucket como myBucket, o Atlas Data Federation gravará o local de saída da seguinte forma:

gcs://myBucket/myPath/myData.[n].json

Obrigatório

gcs.format

objeto

Detalhes do arquivo no Google Cloud Storage.

Obrigatório

gcs
.format
.name

enum

Formato do arquivo no Google Cloud Storage. O valor pode ser um dos seguintes:

  • bson

  • bson.gz

  • csv

  • csv.gz

  • json 1

  • json.gz 1

  • parquet

  • tsv

  • tsv.gz

1 Para este formato, $out grava dados no formato JSON estendido do MongoDB .

Para saber mais, consulte Limitações.

Obrigatório

Campo
Tipo
Descrição
necessidade

atlas

objeto

Local para gravar os documentos a partir da aggregation pipeline.

Obrigatório

clusterName

string

Nome do Atlas cluster.

Obrigatório

coll

string

Nome da coleção no Atlas cluster.

Obrigatório

db

string

Nome do banco de dados no Atlas cluster que contém a coleção.

Obrigatório

projectId

string

Identificador único do projeto que contém o Atlas cluster. O ID do projeto deve ser o ID do projeto que contém sua instância do banco de dados federado. Se omitido, padroniza para o ID do projeto que contém sua instância do banco de dados federado.

Opcional

Opção
Tipo
Descrição
necessidade

background

booleano

Sinalize para executar operações de aggregation em segundo plano. Se omitido, o padrão será false. Quando configurado para true, o Atlas Data Federation executa as queries em segundo plano.

{ "background" : true }

Use essa opção para enviar novas queries sem ter que aguardar queries em execução concluírem ou desconectarem sua conexão de instância do banco de dados federado enquanto as queries continuam sendo executadas em segundo plano.

Opcional

Criar um nome de arquivo

Os exemplos a seguir mostram sintaxes de $out para criar dinamicamente um nome de arquivo a partir de uma string constante ou de campos do mesmo tipo, ou de tipos de dados diferentes nos documentos que chegam ao estágio $out.

Exemplo

Você deseja gravar 1 GiB de dados como arquivos BSON compactados em um bucket S3 chamado my-s3-bucket.

Usando a seguinte sintaxe $out:

1{
2 "$out": {
3 "s3": {
4 "bucket": "my-s3-bucket",
5 "filename": "big_box_store/",
6 "format": {
7 "name": "bson.gz"
8 }
9 }
10 }
11}

O s3.region é omitido e, portanto, o Atlas Data Federation determina a região em que o bucket chamado my-s3-bucket está hospedado a partir da configuração de armazenamento. $out grava cinco arquivos BSON compactados:

  1. O primeiro 200 MiB de dados em um arquivo que $out nomeia big_box_store/1.bson.gz.

    • O valor de s3.filename serve como uma constante em cada nome de arquivo. Este valor não depende de nenhum campo ou valor do documento.

    • O s3.filename termina com um delimitador, o Atlas Data Federation anexará o contador após a constante.

    • Se não terminasse com um delimitador, o Atlas Data Federation teria adicionado um . entre a constante e o contador, como big_box_store.1.bson.gz

    • Como você não alterou o tamanho máximo do arquivo utilizando s3.format.maxFileSize, o Atlas Data Federation usa o valor padrão de 200 MiB.

  2. O segundo 200 MiB de dados para um novo arquivo que $out nomeia big_box_store/2.bson.gz.

  3. Mais três arquivos que $out nomeiam big_box_store/3.bson.gz a big_box_store/5.bson.gz.

Exemplo

Você deseja gravar 90 MiB de dados em arquivos JSON em um bucket S3 chamado my-s3-bucket.

Usando a seguinte sintaxe $out:

1{
2 "$out": {
3 "s3": {
4 "bucket": "my-s3-bucket",
5 "region": "us-east-1",
6 "filename": {"$toString": "$saleDate"},
7 "format": {
8 "name": "json",
9 "maxFileSize": "100MiB"
10 }
11 }
12 }
13}

$out grava 90 MiB de dados em arquivos JSON na raiz do bucket. Cada arquivo JSON contém todos os documentos com o mesmo valor de saleDate. $out nomeia cada arquivo usando o valor de saleDate dos documentos convertido em uma string.

Exemplo

Você deseja gravar 176 MiB de dados como arquivos BSON em um bucket S3 chamado my-s3-bucket.

Usando a seguinte sintaxe $out:

1{
2 "$out": {
3 "s3": {
4 "bucket": "my-s3-bucket",
5 "region": "us-east-1",
6 "filename": {
7 "$concat": [
8 "persons/",
9 "$name", "/",
10 "$uniqueId", "/"
11 ]
12 },
13 "format": {
14 "name": "bson",
15 "maxFileSize": "200MiB"
16 }
17 }
18 }
19}

$out grava 176 MiB de dados em arquivos BSON. Para nomear cada arquivo, $out concatena:

  • Uma string constante persons/ e, a partir dos documentos:

    • O valor de string do campo name,

    • Uma barra (/),

    • O valor de string do campo uniqueId e

    • Uma barra (/).

Cada arquivo BSON contém todos os documentos com os mesmos valores name e uniqueId. $out nomeia cada arquivo usando os valores name e uniqueId dos documentos.

Exemplo

Você deseja gravar 154 MiB de dados como arquivos JSON compactados em um bucket S3 chamado my-s3-bucket.

Considere a seguinte sintaxe $out:

1{
2 "$out": {
3 "s3": {
4 "bucket": "my-s3-bucket",
5 "region": "us-east-1",
6 "filename": {
7 "$concat": [
8 "big-box-store/",
9 {
10 "$toString": "$storeNumber"
11 }, "/",
12 {
13 "$toString": "$saleDate"
14 }, "/",
15 "$partId", "/"
16 ]
17 },
18 "format": {
19 "name": "json.gz",
20 "maxFileSize": "200MiB"
21 }
22 }
23 }
24}

$out grava 154 MiB de dados em arquivos JSON compactados, onde cada arquivo contém todos os documentos com os mesmos valores storeNumber, saleDate e partId. Para nomear cada arquivo, $out concatena:

  • Um valor de string constante de big-box-store/,

  • Um valor de string de um número de armazenamento único no campo storeNumber,

  • Uma barra (/),

  • Um valor de string da data do campo saleDate,

  • Uma barra (/),

  • Um valor de string do ID de parte do campo partId e

  • Uma barra (/).

Criar um nome de arquivo

Os exemplos a seguir mostram sintaxes de $out para criar dinamicamente um nome de arquivo a partir de uma string constante ou de campos do mesmo tipo, ou de tipos de dados diferentes nos documentos que chegam ao estágio $out.

Exemplo

Você deseja gravar 1 GiB de dados como arquivos BSON compactados em uma conta de armazenamento Azure mystorageaccount e em um container chamado my-container.

Usando a seguinte sintaxe $out:

1{
2 "$out": {
3 "azure": {
4 "serviceURL": "http://mystorageaccount.blob.core.windows.net/",
5 "container": "my-container",
6 "filename": "big_box_store/",
7 "format": {
8 "name": "bson.gz"
9 }
10 }
11 }
12}

O azure.region é omitido e, portanto, o Atlas Data Federation determina a região em que o contêiner chamado my-container está hospedado a partir da configuração de armazenamento. $out grava cinco arquivos BSON compactados:

  1. O primeiro 200 MiB de dados em um arquivo que $out nomeia big_box_store/1.bson.gz.

    • O valor de azure.filename serve como uma constante em cada nome de arquivo. Este valor não depende de nenhum campo ou valor do documento.

    • O azure.filename termina com um delimitador, o Atlas Data Federation anexará o contador após a constante.

    • Se não terminasse com um delimitador, o Atlas Data Federation teria adicionado um . entre a constante e o contador, como big_box_store.1.bson.gz

    • Como você não alterou o tamanho máximo do arquivo utilizando azure.format.maxFileSize, o Atlas Data Federation usa o valor padrão de 200 MiB.

  2. O segundo 200 MiB de dados para um novo arquivo que $out nomeia big_box_store/2.bson.gz.

  3. Mais três arquivos que $out nomeiam big_box_store/3.bson.gz a big_box_store/5.bson.gz.

Exemplo

Você deseja gravar 90 MiB de dados em arquivos JSON em um contêiner do Azure Blob Storage denominado my-container.

Usando a seguinte sintaxe $out:

1{
2 "$out": {
3 "azure": {
4 "serviceURL": "http://mystorageaccount.blob.core.windows.net/",
5 "container": "my-container",
6 "region": "eastus2",
7 "filename": {"$toString": "$saleDate"},
8 "format": {
9 "name": "json",
10 "maxFileSize": "100MiB"
11 }
12 }
13 }
14}

$out grava 90 MiB de dados em arquivos JSON na raiz do contêiner. Cada arquivo JSON contém todos os documentos com o mesmo valor de saleDate. $out nomeia cada arquivo usando o valor de saleDate dos documentos convertido em uma string.

Exemplo

Você deseja gravar 176 MiB de dados como arquivos BSON em um contêiner do Azure Blob Storage chamado my-container.

Usando a seguinte sintaxe $out:

1{
2 "$out": {
3 "azure": {
4 "serviceURL": "http://mystorageaccount.blob.core.windows.net/",
5 "container": "my-container",
6 "region": "eastus2",
7 "filename": {
8 "$concat": [
9 "persons/",
10 "$name", "/",
11 "$uniqueId", "/"
12 ]
13 },
14 "format": {
15 "name": "bson",
16 "maxFileSize": "200MiB"
17 }
18 }
19 }
20}

$out grava 176 MiB de dados em arquivos BSON. Para nomear cada arquivo, $out concatena:

  • Uma string constante persons/ e, a partir dos documentos:

    • O valor de string do campo name,

    • Uma barra (/),

    • O valor de string do campo uniqueId e

    • Uma barra (/).

Cada arquivo BSON contém todos os documentos com os mesmos valores name e uniqueId. $out nomeia cada arquivo usando os valores name e uniqueId dos documentos.

Exemplo

Você deseja gravar 154 MiB de dados como arquivos JSON compactados em um contêiner do Azure Blob Storage denominado my-container.

Considere a seguinte sintaxe $out:

1{
2 "$out": {
3 "azure": {
4 "serviceURL": "http://mystorageaccount.blob.core.windows.net/",
5 "container": "my-container",
6 "region": "eastus2",
7 "filename": {
8 "$concat": [
9 "big-box-store/",
10 {
11 "$toString": "$storeNumber"
12 }, "/",
13 {
14 "$toString": "$saleDate"
15 }, "/",
16 "$partId", "/"
17 ]
18 },
19 "format": {
20 "name": "json.gz",
21 "maxFileSize": "200MiB"
22 }
23 }
24 }
25}

$out grava 154 MiB de dados em arquivos JSON compactados, onde cada arquivo contém todos os documentos com os mesmos valores storeNumber, saleDate e partId. Para nomear cada arquivo, $out concatena:

  • Um valor de string constante de big-box-store/,

  • Um valor de string de um número de armazenamento único no campo storeNumber,

  • Uma barra (/),

  • Um valor de string da data do campo saleDate,

  • Uma barra (/),

  • Um valor de string do ID de parte do campo partId e

  • Uma barra (/).

Criar um nome de arquivo

Os exemplos a seguir mostram sintaxes de $out para criar dinamicamente um nome de arquivo a partir de uma string constante ou de campos do mesmo tipo, ou de tipos de dados diferentes nos documentos que chegam ao estágio $out.

Exemplo

Você deseja gravar 1 GiB de dados como arquivos BSON compactados em um bucket do Google Cloud Storage chamado my-gcs-bucket.

Usando a seguinte sintaxe $out:

1{
2 "$out": {
3 "gcs": {
4 "bucket": "my-gcs-bucket",
5 "filename": "big_box_store/",
6 "format": {
7 "name": "bson.gz"
8 }
9 }
10 }
11}

O gcs.region é omitido e, portanto, o Atlas Data Federation determina a região em que o bucket chamado my-gcs-bucket está hospedado a partir da configuração de armazenamento. $out grava cinco arquivos BSON compactados:

  1. O primeiro 200 MiB de dados em um arquivo que $out nomeia big_box_store/1.bson.gz.

    • O valor de gcs.filename serve como uma constante em cada nome de arquivo. Este valor não depende de nenhum campo ou valor do documento.

    • O gcs.filename termina com um delimitador, o Atlas Data Federation anexará o contador após a constante.

    • Se não terminasse com um delimitador, o Atlas Data Federation teria adicionado um . entre a constante e o contador, como big_box_store.1.bson.gz

    • Como você não alterou o tamanho máximo do arquivo utilizando gcs.format.maxFileSize, o Atlas Data Federation usa o valor padrão de 200 MiB.

  2. O segundo 200 MiB de dados para um novo arquivo que $out nomeia big_box_store/2.bson.gz.

  3. Mais três arquivos que $out nomeiam big_box_store/3.bson.gz a big_box_store/5.bson.gz.

Exemplo

Você deseja gravar 90 MiB de dados em arquivos JSON em um bucket do Google Cloud Storage denominado my-gcs-bucket.

Usando a seguinte sintaxe $out:

1{
2 "$out": {
3 "gcs": {
4 "bucket": "my-gcs-bucket",
5 "region": "us-central1",
6 "filename": {"$toString": "$saleDate"},
7 "format": {
8 "name": "json",
9 "maxFileSize": "100MiB"
10 }
11 }
12 }
13}

$out grava 90 MiB de dados em arquivos JSON na raiz do bucket. Cada arquivo JSON contém todos os documentos com o mesmo valor de saleDate. $out nomeia cada arquivo usando o valor de saleDate dos documentos convertido em uma string.

Exemplo

Você deseja gravar 176 MiB de dados como arquivos BSON em um bucket do Google Cloud Storage chamado my-gcs-bucket.

Usando a seguinte sintaxe $out:

1{
2 "$out": {
3 "gcs": {
4 "bucket": "my-gcs-bucket",
5 "region": "us-central1",
6 "filename": {
7 "$concat": [
8 "persons/",
9 "$name", "/",
10 "$uniqueId", "/"
11 ]
12 },
13 "format": {
14 "name": "bson",
15 "maxFileSize": "200MiB"
16 }
17 }
18 }
19}

$out grava 176 MiB de dados em arquivos BSON. Para nomear cada arquivo, $out concatena:

  • Uma string constante persons/ e, a partir dos documentos:

    • O valor de string do campo name,

    • Uma barra (/),

    • O valor de string do campo uniqueId e

    • Uma barra (/).

Cada arquivo BSON contém todos os documentos com os mesmos valores name e uniqueId. $out nomeia cada arquivo usando os valores name e uniqueId dos documentos.

Exemplo

Você quer gravar 154 MiB de dados como arquivos JSON compactados em um bucket do Google Cloud Storage chamado my-gcs-bucket.

Considere a seguinte sintaxe $out:

1{
2 "$out": {
3 "gcs": {
4 "bucket": "my-gcs-bucket",
5 "region": "us-central1",
6 "filename": {
7 "$concat": [
8 "big-box-store/",
9 {
10 "$toString": "$storeNumber"
11 }, "/",
12 {
13 "$toString": "$saleDate"
14 }, "/",
15 "$partId", "/"
16 ]
17 },
18 "format": {
19 "name": "json.gz",
20 "maxFileSize": "200MiB"
21 }
22 }
23 }
24}

$out grava 154 MiB de dados em arquivos JSON compactados, onde cada arquivo contém todos os documentos com os mesmos valores storeNumber, saleDate e partId. Para nomear cada arquivo, $out concatena:

  • Um valor de string constante de big-box-store/,

  • Um valor de string de um número de armazenamento único no campo storeNumber,

  • Uma barra (/),

  • Um valor de string da data do campo saleDate,

  • Uma barra (/),

  • Um valor de string do ID de parte do campo partId e

  • Uma barra (/).

Esta sintaxa $out envia os dados agregados para uma coleção sampleDB.mySampleData no cluster do Atlas chamado myTestCluster. A sintaxe não especifica um ID de projeto; $out usa a ID do projeto que contém sua instância de banco de dados federado.

Exemplo

1{
2 "$out": {
3 "atlas": {
4 "clusterName": "myTestCluster",
5 "db": "sampleDB",
6 "coll": "mySampleData"
7 }
8 }
9}

O exemplo abaixo mostra a sintaxe $out para executar uma pipeline de agregação que termina com o estágio $out em segundo plano.

Exemplo

db.runCommand({
"aggregate": "my-collection",
"pipeline": [
{
"$out": {
"s3": {
"bucket": "my-s3-bucket",
"filename": { "$toString": "$saleDate" }
"format": {
"name": "json"
}
}
}
}
],
{ "background" : true }
})

$out grava em arquivos JSON na raiz do bucket em segundo plano. Cada arquivo JSON contém todos os documentos com o mesmo valor de saleDate. $out nomeia cada arquivo usando o valor de saleDate dos documentos convertido em uma string.

Exemplo

db.runCommand({
"aggregate": "my-collection",
"pipeline": [
{
"$out": {
"azure": {
"serviceURL": "http://mystorageaccount.blob.core.windows.net/",
"container": "my-container",
"filename": {"$toString": "$saleDate"},
"format": {
"name": "json"
}
}
}
}
],
{ "background" : true }
})

$out grava em arquivos JSON na raiz do contêiner do Azure Blob Storage em segundo plano. Cada arquivo JSON contém todos os documentos com o mesmo valor de saleDate. $out nomeia cada arquivo usando o valor de saleDate dos documentos convertido em uma string.

Exemplo

db.runCommand({
"aggregate": "my-collection",
"pipeline": [
{
"$out": {
"gcs": {
"bucket": "my-gcs-bucket",
"filename": { "$toString": "$saleDate" }
"format": {
"name": "json"
}
}
}
}
],
{ "background" : true }
})

$out grava em arquivos JSON na raiz do bucket em segundo plano. Cada arquivo JSON contém todos os documentos com o mesmo valor de saleDate. $out nomeia cada arquivo usando o valor de saleDate dos documentos convertido em uma string.

Exemplo

db.runCommand({
"aggregate": "my-collection",
"pipeline": [
{
"$out": {
"atlas": {
"clusterName": "myTestCluster",
"db": "sampleDB",
"coll": "mySampleData"
}
}
}
],
{ background: true }
})

$out grava na coleção sampleDB.mySampleData no cluster do Atlas chamado myTestCluster em segundo plano.

O Atlas Data Federation interpreta strings vazias ("") como valores null ao analisar nomes de arquivos. Se desejar que Atlas Data Federation gere nomes de arquivos analisáveis, envolva as referências de campo que podem ter null valores usando $convert com um valor de string vazia de onNull .

Exemplo

Este exemplo mostra como gerenciar valores nulos no campo year ao criar um nome de arquivo a partir do valor de campo.

1{
2 "$out": {
3 "s3": {
4 "bucket": "my-s3-bucket",
5 "region": "us-east-1",
6 "filename": {
7 "$concat": [
8 "big-box-store/",
9 {
10 "$convert": {
11 "input": "$year",
12 "to": "string",
13 "onNull": ""
14 }
15 }, "/"
16 ]
17 },
18 "format": {
19 "name": "json.gz",
20 "maxFileSize": "200MiB"
21 }
22 }
23 }
24}

Ao gravar no formato de arquivo CSV, TSV ou Parquet, o Atlas Data Federation não aceita mais de 32.000 campos únicos.

Ao gravar no formato CSV ou TSV, o Atlas Data Federation não aceita os seguintes tipos de dados nos documentos:

  • arrays

  • DB pointer

  • JavaScript

  • JavaScript code with scope

  • Tipo de dados chave mínima ou máxima

Em um arquivo CSV, o Atlas Data Federation representa documentos aninhados utilizando a notação de ponto (.). Por exemplo, o Atlas Data Federation grava { x: { a: 1, b: 2 } } como o seguinte no arquivo CSV:

x.a,x.b
1,2

O Atlas Data Federation representa todos os outros tipos de dados como strings. Portanto, os tipos de dados no MongoDB lidos de volta do arquivo CSV podem não ser os mesmos que os tipos de dados nos documentos BSON originais dos quais os tipos de dados foram gravados.

Para o Parquet, o Atlas Data Federation lê campos com valores nulos ou indefinidos como ausentes porque o Parquet não distingue entre valores nulos ou indefinidos e valores ausentes. Embora o Atlas Data Federation aceite todos os tipos de dados, para tipos de dados BSON que não têm um equivalente direto no Parquet, como JavaScript, expressão regular etc., ele:

  • Escolhe uma representação que permite que o arquivo Parquet resultante seja lido novamente usando uma ferramenta que não seja do MongoDB.

  • Armazena um esquema MongoDB nos metadados chave/valor do arquivo de Parquet para que o Atlas Data Federation possa reconstruir o documento BSON original com os tipos de dados corretos se o arquivo de Parquet for lido de volta pelo Atlas Data Federation.

Exemplo

Considere os seguintes documentos BSON:

{
"clientId": 102,
"phoneNumbers": ["123-4567", "234-5678"],
"clientInfo": {
"name": "Taylor",
"occupation": "teacher"
}
}
{
"clientId": "237",
"phoneNumbers" ["345-6789"]
"clientInfo": {
"name": "Jordan"
}
}

Se você gravar os documentos BSON anteriores no formato Parquet usando $out para S3, o esquema de arquivo Parquet dos seus documentos BSON será algo como:

message root {
optional group clientId {
optional int32 int;
optional binary string; (STRING)
}
optional group phoneNumbers (LIST) {
repeated group list {
optional binary element (STRING);
}
}
optional group clientInfo {
optional binary name (STRING);
optional binary occupation (STRING);
}
}

Seus dados do Parquet no S3 serão semelhantes ao seguinte:

1clientId:
2.int = 102
3phoneNumbers:
4.list:
5..element = "123-4567"
6.list:
7..element = "234-5678"
8clientInfo:
9.name = "Taylor"
10.occupation = "teacher"
11
12clientId:
13.string = "237"
14phoneNumbers:
15.list:
16..element = "345-6789"
17clientInfo:
18.name = "Jordan"

O exemplo anterior demonstra como o Atlas Data Federation lida com tipos de dados complexos:

  • O Atlas Data Federation mapeia documentos em todos os níveis para um grupo de Parquet.

  • O Atlas Data Federation codifica arrays usando o tipo lógico LIST e a estrutura obrigatória de lista ou elemento de três níveis. Para saber mais, consulte Listas.

  • O Atlas Data Federation mapeia campos polimórficos BSON para um grupo de múltiplas colunas de tipo único, pois o Parquet não aceita colunas polimórficas. O Atlas Data Federation nomeia o grupo de acordo com o campo BSON. No exemplo anterior, o Atlas Data Federation cria um grupo de Parquet denominado clientId para o campo polimórfico denominado clientId com dois filhos nomeados de acordo com seus tipos BSON, int stringe.

O Atlas Data Federation interpreta strings vazias ("") como valores null ao analisar nomes de arquivos. Se desejar que Atlas Data Federation gere nomes de arquivos analisáveis, envolva as referências de campo que podem ter null valores usando $convert com um valor de string vazia de onNull .

Exemplo

Este exemplo mostra como gerenciar valores nulos no campo year ao criar um nome de arquivo a partir do valor de campo.

1{
2 "$out": {
3 "azure": {
4 "serviceURL": "http://mystorageaccount.blob.core.windows.net/",
5 "container": "my-container",
6 "region": "eastus2",
7 "filename": {
8 "$concat": [
9 "big-box-store/",
10 {
11 "$convert": {
12 "input": "$year",
13 "to": "string",
14 "onNull": ""
15 }
16 }, "/"
17 ]
18 },
19 "format": {
20 "name": "json.gz",
21 "maxFileSize": "200MiB"
22 }
23 }
24 }
25}

Ao gravar no formato de arquivo CSV, TSV ou Parquet, o Atlas Data Federation não aceita mais de 32.000 campos únicos.

Ao gravar no formato CSV ou TSV, o Atlas Data Federation não aceita os seguintes tipos de dados nos documentos:

  • arrays

  • DB pointer

  • JavaScript

  • JavaScript code with scope

  • Tipo de dados chave mínima ou máxima

Em um arquivo CSV, o Atlas Data Federation representa documentos aninhados utilizando a notação de ponto (.). Por exemplo, o Atlas Data Federation grava { x: { a: 1, b: 2 } } como o seguinte no arquivo CSV:

x.a,x.b
1,2

O Atlas Data Federation representa todos os outros tipos de dados como strings. Portanto, os tipos de dados no MongoDB lidos de volta do arquivo CSV podem não ser os mesmos que os tipos de dados nos documentos BSON originais dos quais os tipos de dados foram gravados.

Para o Parquet, o Atlas Data Federation lê campos com valores nulos ou indefinidos como ausentes porque o Parquet não distingue entre valores nulos ou indefinidos e valores ausentes. Embora o Atlas Data Federation aceite todos os tipos de dados, para tipos de dados BSON que não têm um equivalente direto no Parquet, como JavaScript, expressão regular etc., ele:

  • Escolhe uma representação que permite que o arquivo Parquet resultante seja lido novamente usando uma ferramenta que não seja do MongoDB.

  • Armazena um esquema MongoDB nos metadados chave/valor do arquivo de Parquet para que o Atlas Data Federation possa reconstruir o documento BSON original com os tipos de dados corretos se o arquivo de Parquet for lido de volta pelo Atlas Data Federation.

Exemplo

Considere os seguintes documentos BSON:

{
"clientId": 102,
"phoneNumbers": ["123-4567", "234-5678"],
"clientInfo": {
"name": "Taylor",
"occupation": "teacher"
}
}
{
"clientId": "237",
"phoneNumbers" ["345-6789"]
"clientInfo": {
"name": "Jordan"
}
}

Se você gravar os documentos BSON anteriores no formato Parquet usando $out para o Azure, o esquema de arquivo Parquet dos seus documentos BSON será algo como:

message root {
optional group clientId {
optional int32 int;
optional binary string (STRING);
}
optional group phoneNumbers (LIST) {
repeated group list {
optional binary element (STRING);
}
}
optional group clientInfo {
optional binary name (STRING);
optional binary occupation (STRING);
}
}

Seus dados do Parquet no Azure Blob storage seriam semelhantes ao seguinte:

1clientId:
2.int = 102
3phoneNumbers:
4.list:
5..element = "123-4567"
6.list:
7..element = "234-5678"
8clientInfo:
9.name = "Taylor"
10.occupation = "teacher"
11
12clientId:
13.string = "237"
14phoneNumbers:
15.list:
16..element = "345-6789"
17clientInfo:
18.name = "Jordan"

O exemplo anterior demonstra como o Atlas Data Federation lida com tipos de dados complexos:

  • O Atlas Data Federation mapeia documentos em todos os níveis para um grupo de Parquet.

  • O Atlas Data Federation codifica arrays usando o tipo lógico LIST e a estrutura obrigatória de lista ou elemento de três níveis. Para saber mais, consulte Listas.

  • O Atlas Data Federation mapeia campos polimórficos BSON para um grupo de múltiplas colunas de tipo único, pois o Parquet não aceita colunas polimórficas. O Atlas Data Federation nomeia o grupo de acordo com o campo BSON. No exemplo anterior, o Atlas Data Federation cria um grupo de Parquet denominado clientId para o campo polimórfico denominado clientId com dois filhos nomeados de acordo com seus tipos BSON, int stringe.

O Atlas Data Federation interpreta strings vazias ("") como valores null ao analisar nomes de arquivos. Se desejar que Atlas Data Federation gere nomes de arquivos analisáveis, envolva as referências de campo que podem ter null valores usando $convert com um valor de string vazia de onNull .

Exemplo

Este exemplo mostra como gerenciar valores nulos no campo year ao criar um nome de arquivo a partir do valor de campo.

1{
2 "$out": {
3 "gcs": {
4 "bucket": "my-gcs-bucket",
5 "region": "us-central1",
6 "filename": {
7 "$concat": [
8 "big-box-store/",
9 {
10 "$convert": {
11 "input": "$year",
12 "to": "string",
13 "onNull": ""
14 }
15 }, "/"
16 ]
17 },
18 "format": {
19 "name": "json.gz",
20 "maxFileSize": "200MiB"
21 }
22 }
23 }
24}

Ao gravar no formato de arquivo CSV, TSV ou Parquet, o Atlas Data Federation não aceita mais de 32.000 campos únicos.

Ao gravar no formato CSV ou TSV, o Atlas Data Federation não aceita os seguintes tipos de dados nos documentos:

  • arrays

  • DB pointer

  • JavaScript

  • JavaScript code with scope

  • Tipo de dados chave mínima ou máxima

Em um arquivo CSV, o Atlas Data Federation representa documentos aninhados utilizando a notação de ponto (.). Por exemplo, o Atlas Data Federation grava { x: { a: 1, b: 2 } } como o seguinte no arquivo CSV:

x.a,x.b
1,2

O Atlas Data Federation representa todos os outros tipos de dados como strings. Portanto, os tipos de dados no MongoDB lidos de volta do arquivo CSV podem não ser os mesmos que os tipos de dados nos documentos BSON originais dos quais os tipos de dados foram gravados.

Para o Parquet, o Atlas Data Federation lê campos com valores nulos ou indefinidos como ausentes porque o Parquet não distingue entre valores nulos ou indefinidos e valores ausentes. Embora o Atlas Data Federation aceite todos os tipos de dados, para tipos de dados BSON que não têm um equivalente direto no Parquet, como JavaScript, expressão regular etc., ele:

  • Escolhe uma representação que permite que o arquivo Parquet resultante seja lido novamente usando uma ferramenta que não seja do MongoDB.

  • Armazena um esquema MongoDB nos metadados chave/valor do arquivo de Parquet para que o Atlas Data Federation possa reconstruir o documento BSON original com os tipos de dados corretos se o arquivo de Parquet for lido de volta pelo Atlas Data Federation.

Exemplo

Considere os seguintes documentos BSON:

{
"clientId": 102,
"phoneNumbers": ["123-4567", "234-5678"],
"clientInfo": {
"name": "Taylor",
"occupation": "teacher"
}
}
{
"clientId": "237",
"phoneNumbers" ["345-6789"]
"clientInfo": {
"name": "Jordan"
}
}

Se você gravar os documentos BSON anteriores no formato Parquet usando $out para GCP, o esquema de arquivo Parquet dos seus documentos BSON será algo como:

message root {
optional group clientId {
optional int32 int;
optional binary string; (STRING)
}
optional group phoneNumbers (LIST) {
repeated group list {
optional binary element (STRING);
}
}
optional group clientInfo {
optional binary name (STRING);
optional binary occupation (STRING);
}
}

Seus dados do Parquet no Google Cloud Storage seriam semelhantes ao seguinte:

1clientId:
2.int = 102
3phoneNumbers:
4.list:
5..element = "123-4567"
6.list:
7..element = "234-5678"
8clientInfo:
9.name = "Taylor"
10.occupation = "teacher"
11
12clientId:
13.string = "237"
14phoneNumbers:
15.list:
16..element = "345-6789"
17clientInfo:
18.name = "Jordan"

O exemplo anterior demonstra como o Atlas Data Federation lida com tipos de dados complexos:

  • O Atlas Data Federation mapeia documentos em todos os níveis para um grupo de Parquet.

  • O Atlas Data Federation codifica arrays usando o tipo lógico LIST e a estrutura obrigatória de lista ou elemento de três níveis. Para saber mais, consulte Listas.

  • O Atlas Data Federation mapeia campos polimórficos BSON para um grupo de múltiplas colunas de tipo único, pois o Parquet não aceita colunas polimórficas. O Atlas Data Federation nomeia o grupo de acordo com o campo BSON. No exemplo anterior, o Atlas Data Federation cria um grupo de Parquet denominado clientId para o campo polimórfico denominado clientId com dois filhos nomeados de acordo com seus tipos BSON, int stringe.

Esta seção se aplica somente às ofertas de armazenamento de provedores de serviços em nuvem.

O Atlas Data Federation usa o mecanismo de gerenciamento de erros descrito abaixo para documentos que entram no estágio $out e não podem ser gravados devido a um dos seguintes motivos:

  • O s3.filename não avalia um valor de string.

  • O s3.filename é avaliado como um arquivo que não pode ser gravado.

  • O s3.format.name está configurado para csv, tsv, csv.gz ou tsv.gz e o documento passado para $out contém tipos de dados que não são aceitos pelo formato de arquivo especificado. Para obter uma lista completa dos tipos de dados não aceitos, confira o Formato de arquivo CSV e TSV.

Se $out encontrar um dos erros acima durante o processamento de um documento, o Atlas Data Federation gravará nos três arquivos de erro especiais abaixo usando o caminho s3://<bucket-name>/atlas-data-lake-<correlation-id>/:

Nome do arquivo de erro
Descrição

out-error-docs/<i>.json

O Atlas Data Federation grava o documento que encontrou um erro neste arquivo. i começa com 1 e aumenta sempre que o arquivo que está sendo gravado atinge maxFileSize. Em seguida, todos os documentos adicionais serão gravados no novo arquivo out-error-docs/<i+1>.json.

out-error-index/<i>.json

O Atlas Data Federation grava uma mensagem de erro neste arquivo. Cada mensagem de erro contém uma descrição do erro e um valor de índice n que começa com 0 e incrementos com cada mensagem de erro adicional gravada no arquivo. i começa com 1 e incrementa sempre que o arquivo que está sendo gravado chega ao maxFileSize. Em seguida, todas as outras mensagens de erro serão gravadas no novo arquivo out-error-docs/<i+1>.json.

out-error-summary.json

O Atlas Data Federation grava um único documento de resumo para cada tipo de erro encontrado durante uma operação de aggregation neste arquivo. Cada documento de resumo contém uma descrição do tipo de erro e uma contagem do número de documentos que encontraram este tipo de erro.

Exemplo

Este exemplo mostra como gerar arquivos de erro utilizando $out em uma instância do banco de dados federado.

O pipeline de agregação abaixo classifica os documentos na coleção de conjuntos de dados de amostra analytics.customers por data de nascimento decrescente do consumidor, e tenta gravar os campos _id, name e accounts dos três consumidores mais jovens no arquivo denominado youngest-customers.csv no bucket S3 chamado customer-data.

db.customers.aggregate([
{ $sort: { "birthdate" : -1 } },
{ $unset: [ "username", "address", "email", "tier_and_details", "birthdate" ] },
{ $limit: 3 },
{ $out: {
"s3": {
"bucket": "customer-data",
"filename": "youngest-customers",
"region":"us-east-2",
"format": {
"name": "csv"
}
}
}
])

Como accounts é um campo de array, $out encontra um erro ao tentar gravar um documento no s3.format.name csv. Para gerenciar estes erros, o Atlas Data Federation grava nos três arquivos de erro abaixo:

  • A saída abaixo mostra o primeiro de três documentos gravados no arquivo out-error-docs/1.json:

    s3://customer-data/atlas-data-lake-1773b3d5e2a7f3858530daf5/out-error-docs/1.json
    {
    "_id" : {"$oid":"5ca4bbcea2dd94ee58162ba7"},
    "name": "Marc Cain",
    "accounts": [{"$numberInt":"980440"}, {"$numberInt":"626807"}, {"$numberInt":"313907"}, {"$numberInt":"218101"}, {"$numberInt":"157495"}, {"$numberInt":"736396"}],
    }
  • A saída abaixo mostra o primeiro de três mensagens de erro gravadas no arquivo out-error-index/1.json. O campo n começa em 0 e aumenta para cada erro gravado no arquivo.

    s3://customer-data/atlas-data-lake-1773b3d5e2a7f3858530daf5/out-error-index/1.json
    {
    "n" : {"$numberInt": "0"},
    "error" : "field accounts is of unsupported type array"
    }
  • A saída abaixo mostra o documento de resumo do erro gravado no arquivo out-error-summary . O campo count representa o número de documentos passados para $out que encontraram um erro devido ao campo de array accounts .

    s3://customer-data/atlas-data-lake-1773b3d5e2a7f3858530daf5/out-error-summary.json
    {
    "errorType": "field accounts is of unsupported type array",
    "count": {"$numberInt":"3"}
    }

O Atlas Data Federation usa o mecanismo de gerenciamento de erros descrito abaixo para documentos que entram no estágio $out e não podem ser gravados devido a um dos seguintes motivos:

  • O azure.filename não avalia um valor de string.

  • O azure.filename é avaliado como um arquivo que não pode ser gravado.

  • O azure.format.name está configurado para csv, tsv, csv.gz ou tsv.gz e o documento passado para $out contém tipos de dados que não são aceitos pelo formato de arquivo especificado. Para obter uma lista completa dos tipos de dados não aceitos, confira o Formato de arquivo CSV e TSV.

Se $out encontrar um dos erros acima durante o processamento de um documento, o Atlas Data Federation gravará nos três arquivos de erro especiais abaixo usando o caminho http://<storage-account>.blob.core.windows.net/<container-name>/atlas-data-lake-<correlation-id>/:

Nome do arquivo de erro
Descrição

out-error-docs/<i>.json

O Atlas Data Federation grava o documento que encontrou um erro neste arquivo.

i começa com 1 e incrementa sempre que o arquivo que está sendo gravado atinge maxFileSize. Em seguida, todos os documentos adicionais são gravados no novo arquivo out-error-docs/<i+1>.json.

out-error-index/<i>.json

O Atlas Data Federation grava uma mensagem de erro neste arquivo. Cada mensagem de erro contém uma descrição do erro e um valor de índice n que começa com 0 e incrementos com cada mensagem de erro adicional gravada no arquivo.

i começa com 1 e incrementa sempre que o arquivo que está sendo gravado atinge maxFileSize. Em seguida, todas as outras mensagens de erro serão gravadas no novo arquivo out-error-docs/<i+1>.json.

out-error-summary.json

O Atlas Data Federation grava um único documento de resumo para cada tipo de erro encontrado durante uma operação de aggregation neste arquivo. Cada documento de resumo contém uma descrição do tipo de erro e uma contagem do número de documentos que encontraram este tipo de erro.

Exemplo

Este exemplo mostra como gerar arquivos de erro utilizando $out em uma instância do banco de dados federado.

O pipeline de agregação a seguir classifica documentos na coleção de conjuntos de dados de amostra analytics.customers por data de nascimento do cliente decrescente e tenta gravar os campos _id, name e accounts dos três clientes mais novos no arquivo chamado youngest-customers.csv no contêiner do Azure Blob Storage chamado customer-data.

db.customers.aggregate([
{ $sort: { "birthdate" : -1 } },
{ $unset: [ "username", "address", "email", "tier_and_details", "birthdate" ] },
{ $limit: 3 },
{ $out: {
"azure": {
"serviceURL": "https://myserviceaccount.blob.core.windows.net"
"container": "customer-data",
"filename": "youngest-customers",
"region":"eastus2",
"format": {
"name": "csv"
}
}
}
])

Como accounts é um campo de array, $out encontra um erro ao tentar gravar um documento no azure.format.name csv. Para gerenciar estes erros, o Atlas Data Federation grava nos três arquivos de erro abaixo:

  • A saída abaixo mostra o primeiro de três documentos gravados no arquivo out-error-docs/1.json:

    http://mystorageaccount.blob.core.windows.net/customer-data/atlas-data-lake-1773b3d5e2a7f3858530daf5/out-error-docs/1.json
    {
    "_id" : {"$oid":"5ca4bbcea2dd94ee58162ba7"},
    "name": "Marc Cain",
    "accounts": [{"$numberInt":"980440"}, {"$numberInt":"626807"}, {"$numberInt":"313907"}, {"$numberInt":"218101"}, {"$numberInt":"157495"}, {"$numberInt":"736396"}],
    }
  • A saída abaixo mostra o primeiro de três mensagens de erro gravadas no arquivo out-error-index/1.json. O campo n começa em 0 e aumenta para cada erro gravado no arquivo.

    http://mystorageaccount.blob.core.windows.net/customer-data/atlas-data-lake-1773b3d5e2a7f3858530daf5/out-error-index/1.json
    {
    "n" : {"$numberInt": "0"},
    "error" : "field accounts is of unsupported type array"
    }
  • A saída abaixo mostra o documento de resumo do erro gravado no arquivo out-error-summary . O campo count representa o número de documentos passados para $out que encontraram um erro devido ao campo de array accounts .

    http://mystorageaccount.blob.core.windows.net/customer-data/atlas-data-lake-1773b3d5e2a7f3858530daf5/out-error-summary.json
    {
    "errorType": "field accounts is of unsupported type array",
    "count": {"$numberInt":"3"}
    }

O Atlas Data Federation usa o mecanismo de gerenciamento de erros descrito abaixo para documentos que entram no estágio $out e não podem ser gravados devido a um dos seguintes motivos:

  • O gcs.filename não avalia um valor de string.

  • O gcs.filename é avaliado como um arquivo que não pode ser gravado.

  • O gcs.format.name está configurado para csv, tsv, csv.gz ou tsv.gz e o documento passado para $out contém tipos de dados que não são aceitos pelo formato de arquivo especificado. Para obter uma lista completa dos tipos de dados não aceitos, confira o Formato de arquivo CSV e TSV.

Se $out encontrar um dos erros acima durante o processamento de um documento, o Atlas Data Federation gravará nos três arquivos de erro especiais abaixo usando o caminho gcs://<bucket-name>/atlas-data-lake-<correlation-id>/:

Nome do arquivo de erro
Descrição

out-error-docs/<i>.json

O Atlas Data Federation grava o documento que encontrou um erro neste arquivo. i começa com 1 e aumenta sempre que o arquivo que está sendo gravado atinge maxFileSize. Em seguida, todos os documentos adicionais serão gravados no novo arquivo out-error-docs/<i+1>.json.

out-error-index/<i>.json

O Atlas Data Federation grava uma mensagem de erro neste arquivo. Cada mensagem de erro contém uma descrição do erro e um valor de índice n que começa com 0 e incrementos com cada mensagem de erro adicional gravada no arquivo. i começa com 1 e incrementa sempre que o arquivo que está sendo gravado chega ao maxFileSize. Em seguida, todas as outras mensagens de erro serão gravadas no novo arquivo out-error-docs/<i+1>.json.

out-error-summary.json

O Atlas Data Federation grava um único documento de resumo para cada tipo de erro encontrado durante uma operação de aggregation neste arquivo. Cada documento de resumo contém uma descrição do tipo de erro e uma contagem do número de documentos que encontraram este tipo de erro.

Exemplo

Este exemplo mostra como gerar arquivos de erro utilizando $out em uma instância do banco de dados federado.

O pipeline de agregação a seguir classifica documentos na coleção de conjuntos de dados de amostra analytics.customers por ordem de data de nascimento do cliente e tenta gravar os campos _id, name e accounts dos três clientes mais novos no arquivo chamado youngest-customers.csv no Google bucket do Cloud Storage chamado customer-data.

db.customers.aggregate([
{ $sort: { "birthdate" : -1 } },
{ $unset: [ "username", "address", "email", "tier_and_details", "birthdate" ] },
{ $limit: 3 },
{ $out: {
"gcs": {
"bucket": "customer-data",
"filename": "youngest-customers",
"region":"us-central1",
"format": {
"name": "csv"
}
}
}
])

Como accounts é um campo de array, $out encontra um erro ao tentar gravar um documento no gcs.format.name csv. Para gerenciar estes erros, o Atlas Data Federation grava nos três arquivos de erro abaixo:

  • A saída abaixo mostra o primeiro de três documentos gravados no arquivo out-error-docs/1.json:

    gcs://customer-data/atlas-data-lake-1773b3d5e2a7f3858530daf5/out-error-docs/1.json
    {
    "_id" : {"$oid":"5ca4bbcea2dd94ee58162ba7"},
    "name": "Marc Cain",
    "accounts": [{"$numberInt":"980440"}, {"$numberInt":"626807"}, {"$numberInt":"313907"}, {"$numberInt":"218101"}, {"$numberInt":"157495"}, {"$numberInt":"736396"}],
    }
  • A saída abaixo mostra o primeiro de três mensagens de erro gravadas no arquivo out-error-index/1.json. O campo n começa em 0 e aumenta para cada erro gravado no arquivo.

    gcs://customer-data/atlas-data-lake-1773b3d5e2a7f3858530daf5/out-error-index/1.json
    {
    "n" : {"$numberInt": "0"},
    "error" : "field accounts is of unsupported type array"
    }
  • A saída abaixo mostra o documento de resumo do erro gravado no arquivo out-error-summary . O campo count representa o número de documentos passados para $out que encontraram um erro devido ao campo de array accounts .

    gcs://customer-data/atlas-data-lake-1773b3d5e2a7f3858530daf5/out-error-summary.json
    {
    "errorType": "field accounts is of unsupported type array",
    "count": {"$numberInt":"3"}
    }

Esta seção se aplica somente ao armazenamento do provedor de serviços em nuvem.