Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.
Docs Menu
Docs Home
/ /
Pipeline de agregación
Docs Home
/ /
Características
/
Pipeline de agregación
Docs Home
/
Desarrollo
/
Federación de Datos
/
Características
/
Pipeline de agregación

$out Etapa (Atlas Data Federation)

$out toma los documentos devueltos por el pipeline de agregación y los guarda en una colección especificada. El operador $out debe ser la última etapa del pipeline de agregación. En Atlas Data Federation, puedes usar $out para guardar datos desde cualquiera de los almacenamientos de instancias federadas de base de datos admitidas o desde varios almacenamientos de instancias federadas de base de datos admitidas al usar queries federados en cualquiera de los siguientes:

  • Clúster de Atlas namespace

  • AWS S3 cubos con permisos de lectura y guardar

  • Contenedores de almacenamiento de blobs de Azure con permisos de lectura y escritura

  • Google Cloud Storage (GCS)

Debes conectar a tu instancia federada de base de datos para usar $out.

Permisos requeridos

Debe tener:

  • Una instancia federada de base de datos configurada para un bucket S3 con permisos de lectura y para guardar o permisos de s3:PutObject.

  • Un usuario de MongoDB con el rol atlasAdmin o un rol personalizado con el privilegio outToS3.

Sintaxis

{
  "$out": {
    "s3": {
      "bucket": "<bucket-name>",
      "region": "<aws-region>",
      "filename": "<file-name>",
      "format": {
        "name": "<file-format>",
        "maxFileSize": "<file-size>",
        "maxRowGroupSize": "<row-group-size>",
        "columnCompression": "<compression-type>"
      },
      "errorMode": "stop"|"continue"
    }
  }
}

Campos

Campo
Tipo
Descripción
Necesidad

s3

Objeto

Ubicación para guardar los documentos desde el pipeline de agregación.

Requerido

s3.bucket

string

Nombre del bucket de S3 en el que se guardarán los documentos del pipeline de agregación.

La llamar generada a S3 inserta un / entre s3.bucket y s3.filename. No añada un / a su string s3.bucket.

Por ejemplo, si estableces s3.bucket en myBucket y s3.filename en myPath/myData, Atlas Data Federation escribe la ubicación de salida de la siguiente manera:

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

Requerido

s3.region

string

Nombre de la región AWS en la que se aloja el bucket. Si se omite, utiliza la configuración de la instancia federada de base de datos para determinar la región donde se aloja el s3.bucket especificado.

Opcional

s3.filename

string

Nombre del archivo donde se escribirán los documentos del proceso de agregación. El nombre del archivo puede ser constante o generarse dinámicamente a partir de los campos de los documentos que llegan a la etapa $out. Cualquier expresión de nombre de archivo que proporcione debe evaluarse como un tipo de datos string. Si existen archivos en S3 con el mismo nombre y ruta que los archivos recién generados, $out sobrescribe los archivos existentes con los archivos recién generados.

La llamar generada a S3 inserta un / entre s3.bucket y s3.filename. No anteponga un / a su string s3.filename.

Por ejemplo, si estableces s3.filename en myPath/myData y s3.bucket en myBucket, Atlas Data Federation escribe la ubicación de salida de la siguiente manera:

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

Requerido

s3.format

Objeto

Detalles del archivo en S3.

Requerido

s3
.format
.name

enum

Formato del archivo en S3. El valor puede ser uno de los siguientes:

  • bson

  • bson.gz

  • csv

  • csv.gz

  • json 1

  • json.gz 1

  • parquet

  • tsv

  • tsv.gz

1 Para este formato, $out guarda los datos en formato MongoDB Extended JSON.

Para aprender más, se puede consultar Limitaciones.

Requerido

s3
.format
.maxFileSize

bytes

Tamaño máximo del archivo BSON sin comprimir en S3. Al convertir de BSON al formato preferido, el archivo de salida resultante puede ser más pequeño (por ejemplo, al convertir a Parquet) o más grande (por ejemplo, al convertir a CSV).

Si un documento es mayor que el maxFileSize, Atlas Data Federation guarda el documento en su propio archivo. Se admiten los siguientes sufijos:

  • Base 10, escalado en múltiplos de 1000: B, KB, MB, GB, TB, PB

  • Base 2, escalado en múltiplos de 1024: KiB, MiB, GiB, TiB, PiB

Si se omite, es por defecto 200MiB.

Cuando se alcanza el límite de tamaño de archivo para el archivo actual, Atlas Data Federation crea un nuevo archivo en S3. Adjunta un 1 antes de la extensión del nombre del archivo para el primer archivo. Para cada archivo posterior, Atlas Data Federation incrementa el número adjunto en uno.

Por ejemplo, <filename>.1.<fileformat> y <filename>.2.<fileformat>.

Opcional

s3
.format
.maxRowGroupSize

string

Solo compatible con el formato de archivo Parquet.

Tamaño máximo del grupo de filas a utilizar al escribir en un archivo Parquet. Si se omite, el valor por defecto es 128 MiB o el valor de s3.format.maxFileSize, lo que sea menor. El valor máximo permitido es 1 GB.

Opcional

s3
.format
.columnCompression

string

Solo compatible con el formato de archivo Parquet.

Tipo de compresión a aplicar para comprimir los datos dentro de un archivo Parquet al formatear el archivo Parquet. Valores válidos:

  • gzip

  • snappy

  • uncompressed

Si se omite, es por defecto snappy.

Para obtener más información, consulte Formatos de datos admitidos.

Opcional

errorMode

enum

Especifica cómo debe proceder Atlas Data Federation si hay errores durante el procesamiento de un documento. Por ejemplo, si Atlas Data Federation encuentra un arreglo en un documento cuando Atlas Data Federation escribe en un archivo CSV, Atlas Data Federation usa este valor para determinar si debe o no omitir el documento y procesar otros documentos. Los valores válidos son:

  • continue saltar el documento y continuar procesando los documentos restantes. Atlas Data Federation también guarda el documento que causó el error en un archivo de error.

    Para aprender más información, consulta Errores.

  • stop detenerse en ese punto y no procesar los documentos restantes.

Si se omite, es por defecto continue.

Opcional

opciones

Opción
Tipo
Descripción
Necesidad

background

booleano

Bandera para ejecutar operaciones de agregación en segundo plano. Si se omite, el valor por defecto es false. Cuando se establece en true, Atlas Data Federation ejecuta las consultas en segundo plano.

{ "background" : true }

Utiliza esta opción si deseas enviar otras consultas nuevas sin esperar a que se completen las consultas en curso o desconectar la conexión de tu instancia federada de base de datos mientras las consultas continúan ejecutándose en segundo plano.

Opcional

Ejemplos

Crear un nombre de archivo

Los siguientes ejemplos muestran $out sintaxis para crear dinámicamente un nombre de archivo a partir de un string constante o de los campos de tipos de datos iguales o diferentes en los documentos que llegan a la $out etapa.

Ejemplo de string simple

Se quieren guardar 1 GiB de datos como archivos comprimidos BSON en un bucket S3 llamado my-s3-bucket.

Usando la siguiente sintaxis de $out:

{
  "$out": {
    "s3": {
      "bucket": "my-s3-bucket",
      "filename": "big_box_store/",
      "format": {
        "name": "bson.gz"
      }
    }
  }
}

Se omite el s3.region y, por lo tanto, Atlas Data Federation determina la región donde se aloja el bucket llamado my-s3-bucket a partir de la configuración de almacenamiento. $out guarda cinco archivos BSON comprimidos:

  1. Los primeros 200 MiB de datos a un archivo que $out nombra big_box_store/1.bson.gz.

    • El valor de s3.filename sirve como una constante en cada nombre de archivo. Este valor no depende de ningún campo o valor de documento.

    • Tu s3.filename termina con un delimitador, por lo que Atlas Data Federation añade el contador después de la constante.

    • Si no terminaba con un delimitador, Atlas Data Federation habría agregado un . entre la constante y el contador, como big_box_store.1.bson.gz

    • Como no se cambió el tamaño máximo de archivo con s3.format.maxFileSize, Atlas Data Federation utiliza el valor por defecto de 200 MiB.

  2. Los segundos 200 MiB de datos a un nuevo archivo que $out nombra big_box_store/2.bson.gz.

  3. Tres archivos más que $out se denominan big_box_store/3.bson.gz a big_box_store/5.bson.gz.

Campo único de documentos

Se quieren guardar 90 MiB de datos en archivos JSON en un bucket S3 llamado my-s3-bucket.

Usando la siguiente sintaxis de $out:

{
  "$out": {
    "s3": {
      "bucket": "my-s3-bucket",
      "region": "us-east-1",
      "filename": {"$toString": "$saleDate"},
      "format": {
        "name": "json",
        "maxFileSize": "100MiB"
      }
    }
  }
}

$out escribe 90 MiB de datos en archivos JSON en la raíz del bucket. Cada archivo JSON contiene todos los documentos con el mismo valor saleDate. $out nombra cada archivo usando el valor saleDate de los documentos convertido a una cadena.

Varios campos de documentos

Se quieren guardar 176 MiB de datos en archivos BSON en un bucket S3 llamado my-s3-bucket.

Usando la siguiente sintaxis de $out:

{
  "$out": {
    "s3": {
      "bucket": "my-s3-bucket",
      "region": "us-east-1",
      "filename": {
        "$concat": [
          "persons/",
          "$name", "/",
          "$uniqueId", "/"
        ]
      },
      "format": {
        "name": "bson",
        "maxFileSize": "200MiB"
      }
    }
  }
}

$out escribe 176 MiB de datos en archivos BSON.Para nombrar cada archivo, $out concatena:

  • Una string constante persons/ y, de los documentos:

    • El valor string del campo name,

    • Una barra diagonal (/),

    • El valor de la string del campo uniqueId, y

    • Una barra diagonal (/).

Cada archivo BSON contiene todos los documentos con los mismos valores name y uniqueId. $out nombra cada archivo utilizando los valores name y uniqueId del documento.

Varios tipos de campos de documentos

Se quieren guardar 154 MiB de datos como archivos JSON comprimidos en un bucket S3 llamado my-s3-bucket.

Considere la siguiente $out sintaxis:

{
  "$out": {
    "s3": {
      "bucket": "my-s3-bucket",
      "region": "us-east-1",
      "filename": {
        "$concat": [
          "big-box-store/",
          {
            "$toString": "$storeNumber"
          }, "/",
          {
            "$toString": "$saleDate"
          }, "/",
          "$partId", "/"
        ]
      },
      "format": {
        "name": "json.gz",
        "maxFileSize": "200MiB"
      }
    }
  }
}

$out escribe 154 MiB de datos en archivos JSON comprimidos, donde cada archivo contiene todos los documentos con los mismos valores storeNumber, saleDate y partId. Para nombrar cada archivo, $out concatena:

  • Un valor de cadena constante de big-box-store/,

  • Un valor string que representa la identificación única de una tienda perteneciente al campo storeNumber.

  • Una barra diagonal (/),

  • Un valor de string de la fecha del campo saleDate,

  • Una barra diagonal (/),

  • Un valor de string del identificador de parte del campo partId, y

  • Una barra diagonal (/).

Ejecutar una query en segundo plano

El siguiente ejemplo muestra la sintaxis de $out para ejecutar un pipeline de agregación que termina con la etapa $out en segundo plano.

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

$out escribe en archivos JSON en la raíz del bucket en segundo plano. Cada archivo JSON contiene todos los documentos con el mismo valor saleDate. $out nombra cada archivo usando el valor saleDate de los documentos convertido a un string.

Limitaciones

String Tipo de dato

Atlas Data Federation interpreta las cadenas vacías ("") como valores null al analizar los nombres de archivo. Si desea que Atlas Data Federation genere nombres de archivo analizables, encapsule las referencias de campo que podrían tener valores null utilizando $convert con un valor de string vacía onNull.

Este ejemplo muestra cómo gestionar valores nulos en el campo year al crear un nombre de archivo a partir del valor del campo.

{
  "$out": {
    "s3": {
      "bucket": "my-s3-bucket",
      "region": "us-east-1",
      "filename": {
        "$concat": [
          "big-box-store/",
          {
            "$convert": {
              "input": "$year",
              "to": "string",
              "onNull": ""
            }
          }, "/"
        ]
      },
      "format": {
        "name": "json.gz",
        "maxFileSize": "200MiB"
      }
    }
  }
}

Número de campos únicos

Al escribir en formato de archivo CSV, TSV o Parquet, Atlas Data Federation no admite más de 32000 campos únicos.

Formato de archivo CSV y TSV

Al escribir en formato CSV o TSV, Atlas Data Federation no admite los siguientes tipos de datos en los documentos:

  • Arreglos

  • DBPointer

  • JavaScript

  • Código JavaScript con alcance

  • Tipo de dato mínimo o máximo de clave

En un archivo CSV, Atlas Data Federation representa los documentos anidados mediante la notación de punto (.). Por ejemplo, Atlas Data Federation guarda { x: { a: 1, b: 2 } } como lo siguiente en el archivo CSV:

x.a,x.b
1,2

Atlas Data Federation representa todos los demás tipos de datos como cadenas de texto. Por lo tanto, los tipos de datos en MongoDB leídos desde el archivo CSV pueden no ser los mismos que los tipos de datos en los documentos BSON originales desde los cuales se escribieron los tipos de datos.

Formato de archivo Parquet

Para Parquet, Atlas Data Federation lee los campos que tienen valores nulos o no definidos como faltantes, porque Parquet no distingue entre valores nulos o no definidos y valores faltantes. Aunque Atlas Data Federation admite todos los tipos de datos, para los tipos de datos BSON que no tienen un equivalente directo en Parquet, como JavaScript, expresiones regulares, etc.:

  • Elige una representación que permita que el archivo Parquet resultante pueda leerse con una herramienta ajena a MongoDB.

  • Almacena un esquema de MongoDB en los metadatos de clave/valor del archivo Parquet para que Atlas Data Federation pueda reconstruir el documento BSON original BSON original con los tipos de datos correctos si Atlas Data Federation vuelve a leer el archivo Parquet.

Considerar los siguientes documentos BSON:

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

Si escribe los documentos BSON anteriores en formato Parquet usando $out a S3, el esquema del archivo Parquet para sus documentos BSON se vería similar al siguiente:

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);
  }
}

Sus datos Parquet en S3 tendrían un aspecto similar al siguiente:

clientId:
.int = 102
phoneNumbers:
.list:
..element = "123-4567"
.list:
..element = "234-5678"
clientInfo:
.name = "Taylor"
.occupation = "teacher"
clientId:
.string = "237"
phoneNumbers:
.list:
..element = "345-6789"
clientInfo:
.name = "Jordan"

El ejemplo anterior demuestra cómo Atlas Data Federation gestiona los tipos de datos complejos:

  • Atlas Data Federation mapea documentos en todos los niveles a un grupo Parquet.

  • Atlas Data Federation codifica arreglos usando el tipo lógico LIST y la estructura obligatoria de lista o elemento de tres niveles. Para obtener más información, consulta Listas.

  • Atlas Data Federation asigna campos BSON polimórficos a un grupo de múltiples columnas de tipo único porque Parquet no admite columnas polimórficas. Atlas Data Federation nombra al grupo según el campo BSON. En el ejemplo anterior, Atlas Data Federation crea un grupo Parquet denominado clientId para el campo polimórfico denominado clientId con dos elementos secundarios denominados según sus tipos BSON, int y string.

Salida de errores

Atlas Data Federation utiliza el mecanismo de gestión de errores que se describe a continuación para los documentos que entran en la fase $out y no se pueden escribir por uno de los siguientes motivos:

  • El s3.filename no se evalúa como un valor de string.

  • El s3.filename se evalúa como un archivo al que no se puede escribir.

  • s3.format.name está configurado en csv, tsv, csv.gz o tsv.gz y el documento pasado a $out contiene tipos de datos no admitidos por el formato de archivo especificado. Para obtener una lista completa de tipos de datos no admitidos, consulta Formato de archivo CSV y TSV.

Si $out encuentra uno de los errores anteriores durante el procesamiento de un documento, Atlas Data Federation guardar en los tres archivos de error especiales siguientes en la ruta s3://<bucket-name>/atlas-data-lake-<correlation-id>/:

Nombre del archivo de error
Descripción

out-error-docs/<i>.json

Atlas Data Federation guarda el documento que tuvo un error en este archivo. i comienza con 1 y se incrementa cada vez que el archivo en el que se escribe alcanza el maxFileSize. Luego, cualquier otro documento se escribe en el nuevo archivo out-error-docs/<i+1>.json.

out-error-index/<i>.json

Atlas Data Federation guarda un mensaje de error en este archivo. Cada mensaje de error contiene una descripción del error y un valor de índice n que comienza con 0 y se incrementa con cada mensaje de error adicional escrito en el archivo. i comienza con 1 y se incrementa cada vez que el archivo al que se escribe alcanza el maxFileSize. A continuación, cualquier mensaje de error adicional se escribe en el nuevo archivo out-error-docs/<i+1>.json.

out-error-summary.json

Atlas Data Federation escribe un único documento resumen para cada tipo de error encontrado durante una operación de agregación en este archivo. Cada documento resumen contiene una descripción del tipo de error y un recuento del número de documentos que encontraron ese tipo de error.

Este ejemplo muestra cómo generar archivos de error utilizando $out en una instancia federada de base de datos.

El siguiente pipeline de agregación ordena los documentos en la colección de conjuntos de datos de muestra analytics.customers en orden descendente de fecha de nacimiento del cliente e intenta guardar los campos _id, name y accounts de los tres clientes más jóvenes en el archivo denominado youngest-customers.csv en el bucket S3 denominado customer-data.

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

Debido a que accounts es un campo de arreglo, $out encuentra un error cuando intenta guardar un documento en s3.format.name csv. Para gestionar estos errores, Atlas Data Federation guarda en los siguientes tres archivos de error:

  • La siguiente salida muestra el primero de tres documentos escritos en el archivo 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"}]
    }

  • La siguiente salida muestra el primero de tres mensajes de error escritos en el archivo out-error-index/1.json. El campo n comienza en 0 y aumenta por cada error escrito en el archivo.

    s3://cliente-data/atlas-lago de datos-1773b3d5e2a7f3858530daf5/out-error-índice/1.json
    {
      "n" : {"$numberInt": "0"},
      "error" : "field accounts is of unsupported type array"
    }

  • La siguiente salida muestra el documento de resumen de errores escrito en el archivo out-error-summary. El campo count representa el número de documentos pasados a $out que encontraron un error debido al campo de arreglo accounts.

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

Tip

Volver
$merge
Next
$sql
Califique esta página

En esta página