Cómo exportar una tabla de DynamoDB a CSV

DynamoDB no tiene un botón nativo de "exportar a CSV". Cada valor vuelve envuelto en el JSON marshalled de DynamoDB — {"S": "..."}, {"N": "123"}, {"M": {...}} — y una tabla puede contener mapas, listas y conjuntos anidados sin una representación obvia en columnas planas. Así que "exportar DynamoDB a CSV" son en realidad dos problemas: sacar los elementos y luego aplanar el JSON tipado en filas. Ni la consola ni la exportación gestionada hacen el segundo paso por ti.

Esta guía empieza por el camino que hace ambos pasos por ti, y luego cubre las tres rutas con herramientas de AWS y cuándo cada una es la elección correcta.

¿Cómo exporto una tabla de DynamoDB a CSV?

La forma más rápida: abre la tabla en DynoTable, filtra hasta las filas que quieres y exporta el resultado a CSV en un clic — con los descriptores de tipo desenvueltos y los valores anidados aplanados por ti (Método 1). Construyéndolo con herramientas de AWS en su lugar: escanea con la CLI y reforma con jq para una tabla pequeña (Método 2), usa la exportación gestionada a S3 para tablas grandes (Método 3), o escribe un script corto cuando necesites un formato a medida (Método 4).

CSV filtrado / con forma (un subconjunto de columnas, solo algunos elementos): una exportación con GUI (Método 1) o un script. La exportación gestionada a S3 te da la tabla entera, sin filtrar.
Tabla pequeña, ad hoc, solo terminal: scan de la AWS CLI + jq (Método 2). Va bien hasta que aparecen atributos anidados.
Tabla grande (GBs o más): exportación de DynamoDB a S3 (Método 3), y luego convierte el volcado. Se ejecuta de forma asíncrona y no consume capacidad de lectura — pero produce DynamoDB JSON, no CSV.

Método 1: exportación con un clic en DynoTable

DynoTable trata la exportación como parte de la navegación: ejecuta o filtra una consulta, pulsa ⌘⇧E (o el botón Exportar de la barra de herramientas de la pestaña) y elige qué sale:

Formatos: CSV (una fila por elemento, con cabeceras — los conjuntos se serializan como arrays JSON dentro de una celda), JSON y NDJSON. JSON/NDJSON salen sin marshalling (un "count": 3 plano) o como DynamoDB-JSON marshalled cuando necesitas un viaje de ida y vuelta sin pérdidas que preserve los números grandes.
Alcances: las filas cargadas actualmente, solo tu selección, o la coincidencia completa del filtro — cada elemento que tu consulta coincide, transmitido directamente desde DynamoDB en lugar de solo lo que está en pantalla. Ese último es la exportación filtrada que la instantánea gestionada de S3 no puede hacer.
Destino: portapapeles o archivo. Para capturas puntuales, haz clic derecho en una fila y Copiar como… pone CSV, JSON, NDJSON o DynamoDB-JSON directamente en el portapapeles, sin diálogo.

El diálogo de exportación de DynoTable: formato (CSV / JSON / NDJSON), alcance desde la selección hasta la coincidencia completa del filtro, y destino portapapeles o archivo.

Los problemas de aplanado que rompen las rutas manuales de abajo están resueltos: los descriptores de tipo se desenvuelven, los mapas y listas anidados se aplanan, y las columnas renombradas fluyen hasta las cabeceras del CSV. Las exportaciones grandes se desacoplan y corren en segundo plano — transmitidas a disco fila a fila, sobreviviendo a cambios de pestaña e incluso a una recarga de la app — así que una exportación de varios gigabytes nunca tiene que caber en memoria.

Es un cliente de escritorio de DynamoDB, la misma herramienta que ya usas para explorar la tabla; mira cómo se compara con otras GUIs de DynamoDB. ¿Cuándo no lo usarías? Cuando la exportación debe correr desatendida en un pipeline — para eso está la ruta del script (Método 4).

Método 2: scan de la AWS CLI + jq

Para una tabla pequeña puedes escanearla y reformar la salida con jq. Un Scan lee cada elemento de la tabla y lo devuelve en páginas de hasta 1 MB; la CLI sigue la paginación por ti automáticamente (documentación de AWS: escanear tablas).

aws dynamodb scan --table-name MyTable --output json \
  | jq -r '.Items[] | [.id.S, .name.S, .price.N] | @csv' \
  > out.csv

La pega está en esa línea de jq: tienes que escribir a mano .id.S, .name.S, .price.N — pasando por encima del descriptor de tipo de cada atributo (S, N, B, BOOL, M, L, SS, NS, BS) para llegar al valor crudo. Eso es manejable para una tabla plana con tres columnas de cadena. Se desmorona en cuanto tienes:

Mapas/listas anidados — {"M": {...}} o {"L": [...]} no tienen una sola columna en la que aplanarse; @csv se atraganta, o codificas la celda como JSON a mano.
Conjuntos — {"SS": ["a","b"]} es un array, no un escalar.
Atributos dispersos — DynamoDB no tiene schema, así que el elemento A puede tener un price y el elemento B no. Tu lista fija de columnas descarta o desalinea columnas en silencio.

Tampoco existe un --output csv en absoluto — los formatos de salida de la CLI son json, yaml, text, table y off, y ninguno entiende los tipos de DynamoDB. Así que sigues necesitando jq (o un script) para quitar las etiquetas de tipo. Esa es la razón de fondo por la que "exportar una tabla de DynamoDB a CSV con la AWS CLI" nunca es una sola línea más allá del caso trivial.

Para exportar así una tabla grande entera sin que tarde todo el día, paraleliza el scan con --segment / --total-segments (documentación de AWS: scan paralelo — DynamoDB "asigna los elementos a segmentos aplicando una función hash a la clave de partición de cada elemento", así que los segmentos pueden ser desiguales), y lee paginación para no detenerte en la primera página de 1 MB.

Método 3: exportación de DynamoDB a S3 (tablas grandes)

Para tablas de cualquier tamaño real, la exportación gestionada a Amazon S3 es la herramienta correcta. Exporta una instantánea desde cualquier punto de tu ventana de recuperación a un momento dado (PITR) — así que PITR debe estar habilitado en la tabla primero, o la exportación falla con PointInTimeRecoveryUnavailableException —, se ejecuta de forma asíncrona y no consume unidades de capacidad de lectura, por lo que tiene cero impacto en el rendimiento o la disponibilidad de tu tabla (documentación de AWS: "Las exportaciones son asíncronas, no consumen unidades de capacidad de lectura (RCUs) y no tienen impacto en el rendimiento y la disponibilidad de la tabla"; "Necesitas habilitar PITR en tu tabla para usar la funcionalidad de exportación"). Esto es también lo que la acción Exports to S3 de la consola dispara por debajo: la consola es solo una fachada de la misma API, así que arrastra el mismo requisito de PITR y la misma salida en JSON.

aws dynamodb export-table-to-point-in-time \
  --table-arn arn:aws:dynamodb:us-east-1:123456789012:table/MyTable \
  --s3-bucket my-export-bucket \
  --export-format DYNAMODB_JSON

El único inconveniente: la exportación a S3 no produce CSV. Escribe solo DynamoDB JSON o Amazon Ion, como archivos comprimidos con gzip en formato JSON-lines (un elemento por línea), más archivos de manifiesto (documentación de AWS: formato de salida de la exportación — los archivos de datos se escriben como .json.gz, "el formato es JSON lines", junto a manifest-summary.json / manifest-files.json). Después sigues necesitando un paso de conversión:

Athena / Glue leen el DynamoDB JSON exportado directamente — apunta una tabla al prefijo de S3 y luego escribe CSV desde un SELECT (este es el pipeline habitual de "exportar DynamoDB a S3 y luego a CSV"). AWS señala que "muchos servicios de AWS, como Athena y AWS Glue, analizarán este formato automáticamente" (formato de salida de la exportación).
Hazlo tú mismo — descomprime los archivos .gz, analiza cada línea JSON y aplánala (el mismo problema de aplanado que en cualquier otro método).

También es una instantánea de tabla completa: no hay filtro del lado del servidor para exportar solo algunos elementos. Si necesitas un subconjunto, o filtras después en Athena, o usas una GUI (Método 1) / un script en su lugar.

Método 4: un script rápido (boto3 / Node)

Cuando la exportación debe correr desatendida — un trabajo nocturno, un paso de CI — un script pequeño gana a todo lo anterior. La ventaja es que los SDKs de AWS desmarshalizan el JSON tipado por ti: la interfaz de recursos de boto3 y el DynamoDBDocumentClient del SDK de JS devuelven un {"price": 2000} plano en lugar de {"price": {"N": "2000"}} (la interfaz de recursos de boto3 hace "el tipado de datos implícito", según la guía de Python de AWS; el DocumentClient de JS "convierte los datos de respuesta anotados en tipos nativos de JavaScript", según @aws-sdk/lib-dynamodb).

import boto3, csv

table = boto3.resource("dynamodb").Table("MyTable")
rows, resp = [], table.scan()
rows += resp["Items"]
while "LastEvaluatedKey" in resp:                  # paginate to the end
    resp = table.scan(ExclusiveStartKey=resp["LastEvaluatedKey"])
    rows += resp["Items"]

with open("out.csv", "w", newline="") as f:
    w = csv.DictWriter(f, fieldnames=["id", "name", "price"])
    w.writeheader()
    for r in rows:
        w.writerow({k: r.get(k) for k in w.fieldnames})

Sigues siendo dueño de dos decisiones que el SDK no puede tomar por ti: cómo aplanar mapas/listas anidados en columnas (¿codificar la celda como JSON? ¿rutas con puntos en las claves?), y qué hacer con los atributos dispersos (aquí una clave ausente se convierte en una celda vacía mediante r.get(k)). Y no te saltes el bucle de LastEvaluatedKey — una sola llamada a scan() devuelve solo la primera página de 1 MB, así que sin él exportas en silencio solo parte de la tabla.

La misma advertencia que en el Método 2: un scan de tabla completa aquí sigue consumiendo capacidad de lectura y compitiendo con el tráfico en vivo. Para una tabla grande, prefiere el Método 3 y reforma el volcado.

Trampas: DynamoDB JSON vs CSV plano

Elijas el método que elijas, el mismo puñado de desajustes entre el modelo de datos de DynamoDB y un CSV plano te morderá:

Descriptores de tipo. La salida cruda de la API / CLI / exportación a S3 envuelve cada valor ({"S": "..."}, {"N": "123"}). O lo desenvuelves con un SDK o quitas el descriptor tú mismo. El conjunto completo es S, N, B, BOOL, NULL, M, L, SS, NS, BS — consulta tipos de datos de DynamoDB.
Los mapas y listas anidados (M, L) pueden anidarse hasta 32 niveles de profundidad (documentación de AWS: tipos de datos — lista y mapa "pueden anidarse entre sí para representar estructuras de datos complejas de hasta 32 niveles de profundidad") y no tienen una forma natural de columna única. Decide por adelantado: codificar la celda como JSON, o desplegar las claves anidadas en columnas con rutas de puntos (address.city).
Los conjuntos (SS/NS/BS) son colecciones sin orden, no escalares — AWS advierte que "el orden de los valores dentro de un conjunto no se preserva" (tipos de datos) — así que aplana a una cadena delimitada y no dependas del orden de los elementos.
Atributos dispersos. DynamoDB no tiene schema, así que dos elementos pueden tener atributos distintos. No hay un conjunto fijo de columnas; une las claves de todos los elementos o las columnas se desalinearán. Esta es una consecuencia directa del diseño de tabla única, donde una tabla contiene varias formas de entidad.
Paginación. Scan (y Query) devuelven como máximo 1 MB por llamada. Si no iteras sobre LastEvaluatedKey exportarás en silencio solo la primera página. Consulta paginación.
Precisión numérica. Los números de DynamoDB llevan hasta 38 dígitos de precisión y viajan como cadenas (documentación de AWS: tipos de datos: "Los números pueden tener hasta 38 dígitos de precisión"; "Todos los números se envían por la red a DynamoDB como cadenas"); el software de hojas de cálculo puede convertir números largos o IDs en floats y perder dígitos. Mantenlos como texto.

FAQ

¿Cuál es la forma más rápida de exportar una tabla de DynamoDB a CSV? Una GUI que haga el aplanado por ti: en DynoTable, filtra la tabla, pulsa ⌘⇧E, elige CSV y escoge un alcance — desde las filas seleccionadas hasta cada elemento que el filtro coincide, transmitido desde DynamoDB. Los descriptores de tipo y los valores anidados se manejan automáticamente.

¿Cómo exporto una tabla de DynamoDB a CSV con la AWS CLI? Escanea la tabla y reforma la salida con jq (Método 2): aws dynamodb scan → jq para quitar el descriptor de tipo de cada valor → @csv. No hay un --output csv que entienda DynamoDB, así que el quitado de tipos siempre lo haces tú, y se rompe con mapas, listas y conjuntos anidados.

¿Puedo exportar una tabla de DynamoDB directamente a CSV desde AWS? No en un solo paso. La consola y la exportación gestionada a S3 producen ambas DynamoDB JSON o Amazon Ion, nunca CSV. Siempre necesitas un paso de conversión — CLI + jq, un script, Athena/Glue sobre el volcado de S3, o una GUI que haga el aplanado por ti.

¿Cómo exporto una tabla de DynamoDB entera sin afectar a producción? Usa la funcionalidad de exportación a S3 (Método 3). Se ejecuta de forma asíncrona y no consume unidades de capacidad de lectura, así que no compite con el tráfico en vivo — a diferencia de un Scan, que se mide contra el rendimiento de tu tabla (documentación de AWS). Requiere PITR habilitado y exporta la tabla completa, no un subconjunto filtrado.

¿Cómo exporto DynamoDB a S3 como CSV? La exportación gestionada solo escribe DynamoDB JSON / Ion en S3, así que "a CSV" es un segundo salto: registra el prefijo de la exportación como una tabla de Athena (o Glue) y escribe CSV desde un SELECT. No existe --export-format CSV.

¿Cómo exporto DynamoDB a Excel? Exporta primero a CSV (cualquier método de arriba) y luego abre el CSV en Excel — manteniendo los IDs numéricos largos como texto para que no se conviertan en floats. No hay exportación directa a .xlsx desde DynamoDB; DynoTable guarda la vista actual directamente en un CSV listo para hoja de cálculo.

¿Por qué mi JSON exportado tiene {"S": ...} y {"N": ...} por todas partes? Ese es el formato de cable de DynamoDB — cada valor está etiquetado con un descriptor de tipo. Desmarshalízalo con un SDK, el conversor de DynamoDB JSON o una GUI antes de escribir el CSV. El formato de cable es el mismo tanto si los datos vinieron de la API, de la CLI o de la exportación a S3.

Explora, filtra y exporta tus propias tablas a CSV con DynoTable, o desenvuelve primero una muestra de DynamoDB JSON en el conversor de JSON.