Trabajo con resultados de las consultas, consultas recientes y archivos de salida

Amazon Athena almacena de forma automática los resultados y la información de metadatos de cada consulta que se ejecuta en una ubicación de resultados de consulta que puede especificar en Amazon S3. Si es necesario, puede obtener acceso a los archivos de esta ubicación para trabajar con ellos. También puede descargar archivos de resultados de consultas directamente desde la consola de Athena.

Para configurar una ubicación de resultados de consulta de Amazon S3 por primera vez, consulte Especificación de una ubicación de resultados de consulta mediante la consola de Athena.

Los archivos de salida se guardan automáticamente por cada consulta que se hace. Para acceder y ver los archivos de salida de la consulta con la consola de Athena, las entidades principales de IAM (usuarios y roles) necesitan permiso para la acción GetObject de Amazon S3 para la ubicación del resultado de la consulta, así como permiso para la acción GetQueryResults de Athena. La ubicación del resultado de la consulta puede estar cifrada. Si la ubicación está cifrada, los usuarios deben tener los permisos de clave adecuados para cifrar y descifrar la ubicación del resultado de la consulta.

importante

Las entidades principales de IAM con permiso para la acción GetObject de Amazon S3 para la ubicación del resultado de la consulta pueden recuperar los resultados de la consulta de Amazon S3, incluso si se deniega el permiso para la acción GetQueryResults de Athena.

Especificación de una ubicación de resultados de consulta

La ubicación de los resultados de la consulta que Athena utiliza viene determinada por una combinación de configuración del grupo de trabajo y la configuración del lado del cliente. La configuración del lado del cliente se basa en cómo se ejecuta la consulta.

• Si ejecuta la consulta con la consola de Athena, la ubicación del resultado de la consulta, ingresada en Settings (Configuración) en la barra de navegación, determina la configuración del lado del cliente.

• Si ejecuta la consulta con la API de Athena, el parámetro OutputLocation de la acción StartQueryExecution determina la configuración del lado del cliente.

• Si utiliza los controladores ODBC o JDBC para ejecutar consultas, la propiedad S3OutputLocation especificada en la URL de conexión determina la configuración del lado del cliente.

importante

Cuando se ejecuta una consulta con la API o con el controlador ODBC o JDBC, la configuración de la consola no se aplica.

Cada configuración de grupo de trabajo tiene una opción Override client-side settings (Anular configuración del lado del cliente) que se puede habilitar. Cuando esta opción está habilitada, la configuración del grupo de trabajo prevalece sobre la configuración del lado del cliente aplicable cuando una entidad principal de IAM asociada a ese grupo de trabajo ejecuta la consulta.

Especificación de una ubicación de resultados de consulta mediante la consola de Athena

Antes de poder ejecutar una consulta, se debe especificar una ubicación de bucket de resultado de consulta en Amazon S3 o debe utilizar un grupo de trabajo que tenga especificado un bucket y cuya configuración sobrescriba la configuración del cliente.

Para especificar una ubicación de resultados de consulta de configuración del lado del cliente mediante la consola de Athena

1. Cambie al grupo de trabajo para el que desea especificar una ubicación de resultados de consulta. El nombre del grupo de trabajo predeterminado es Primary (Principal).

2. En la barra de navegación, elija Settings (Configuración).

3. En la barra de navegación, elija Manage (Administrar).

4. En Manage settings (Administrar configuración), realice una de las siguientes operaciones:

   • En el cuadro Location of query result (Ubicación del resultado de la consulta), ingrese la ruta de acceso al bucket que creó en Amazon S3 para los resultados de la consulta. Prefije la ruta con s3://.

   • Elija Browse S3 (Navegar S3), elija el bucket de Amazon S3 que creó para su región actual y, a continuación, elija Choose (Elegir).

   nota

   Si utiliza un grupo de trabajo que especifica una ubicación del resultado de la consulta para todos los usuarios del grupo de trabajo, la opción para cambiar la ubicación del resultado de la consulta no estará disponible.

5. (Opcional) Seleccione View lifecycle configuration (Ver configuración del ciclo de vida) para ver y configurar las reglas del ciclo de vida de Amazon S3 en el bucket de resultados de consultas. Las reglas del ciclo de vida de Amazon S3 que cree pueden ser reglas de caducidad o reglas de transición. Las reglas de caducidad eliminan automáticamente los resultados de consultas transcurrido cierto tiempo. Las reglas de transición los mueven a otro nivel de almacenamiento de Amazon S3. Para obtener más información, consulte Configurar el ciclo de vida de un bucket en la Guía del usuario de Amazon Simple Storage Service.

6. (Opcional) En Expected bucket owner (Propietario esperado del bucket), ingrese el ID de la Cuenta de AWS que espera que sea el propietario del bucket de ubicación de salida. Se trata de una medida de seguridad añadida. Si el ID de cuenta del propietario del bucket no coincide con el ID que se especifique aquí, los intentos de generar el bucket fallarán. Para obtener información detallada, consulte Verificación de la propiedad del bucket con la condición de propietario del bucket en la Guía del usuario de Amazon S3.

   nota

   La configuración del propietario esperado del bucket se aplica solo a la ubicación de salida de Amazon S3 especificada para los resultados de las consultas de Athena. No se aplica a otras ubicaciones de Amazon S3, como las ubicaciones de origen de datos en buckets externos de Amazon S3, ubicaciones de tablas de destino de CTAS y INSERT INTO, ubicaciones de salida de instrucciones UNLOAD, operaciones para desbordar buckets para consultas federadas, o consultas SELECT ejecutadas en una tabla de otra cuenta.

7. (Opcional) Elija Encrypt query results (Cifrar los resultados de las consultas) si desea cifrar los resultados de las consultas almacenados en Simple Storage Service (Amazon S3). Para obtener más información sobre el cifrado en Athena, consulte Cifrado en reposo.

8. (Opcional) Elija Assign bucket owner full control over query results (Asignar control total sobre los resultados de las consultas al propietario del bucket) para conceder acceso de control total sobre los resultados de las consultas al propietario del bucket cuando estén habilitadas las ACL para el bucket de resultados de las consultas. Por ejemplo, si la ubicación del resultado de las consultas es propiedad de otra cuenta, puede conceder la propiedad y el control total sobre los resultados de las consultas a la otra cuenta. Para obtener más información, consulte Control de la propiedad de los objetos y desactivación de las ACL del bucket en la Guía del usuario de Simple Storage Service (Amazon S3).

9. Seleccione Guardar.

Ubicaciones predeterminadas creadas anteriormente

Anteriormente en Athena, si ejecutaba una consulta sin especificar un valor para Query result location (Ubicación de resultado de consulta) y un grupo de trabajo no anulaba la configuración de la ubicación del resultado de la consulta, Athena creaba una ubicación predeterminada automáticamente. La ubicación predeterminada era aws-athena-query-results-MyAcctID-MyRegion, donde MyAcctID era el ID de cuenta de Amazon Web Services de la entidad principal de IAM que ejecutaba la consulta y MyRegion era la región donde se ejecutaba la consulta (por ejemplo, us-west-1).

Ahora, antes de poder ejecutar una consulta de Athena en una región en la que su cuenta no haya utilizado Athena anteriormente, debe especificar una ubicación de resultado de la consulta o utilizar un grupo de trabajo que anule la configuración de ubicación del resultado de la consulta. Aunque Athena ya no crea una ubicación predeterminada de resultados de consulta, las ubicaciones aws-athena-query-results-MyAcctID-MyRegion predeterminadas creadas anteriormente siguen siendo válidas y puede seguir utilizándolas.

Especificación de una ubicación de resultados de consulta mediante un grupo de trabajo

Puede especificar la ubicación del resultado de la consulta en una configuración de grupo de trabajo mediante la AWS Management Console, la AWS CLI o la API de Athena.

Cuando utilice la AWS CLI, especifique la ubicación del resultado de la consulta mediante el parámetro OutputLocation de la opción --configuration cuando ejecute el comando aws athena create-work-group o aws athena update-work-group.

Para especificar la ubicación del resultado de la consulta para un grupo de trabajo mediante la consola de Athena

1. Si el panel de navegación de la consola no está visible, elija el menú de expansión de la izquierda.

   

2. En el panel de navegación, elija Workgroups (Redes globales).

3. En la lista de grupos de trabajo, elija el enlace del grupo de trabajo que quiere editar.

4. Elija Editar.

5. Para Ubicación de resultados de consulta y cifrado, realice una de las siguientes operaciones:

   • En el cuadro Location of query result (Ubicación del resultado de la consulta), ingrese la ruta de acceso al bucket de Amazon S3 para los resultados de la consulta. Prefije la ruta con s3://.

   • Elija Browse S3 (Navegar S3), elija el bucket de Amazon S3 para la región actual que quiere utilizar y, a continuación, elija Choose (Elegir).

6. (Opcional) En Expected bucket owner (Propietario esperado del bucket), ingrese el ID de la Cuenta de AWS que espera que sea la propietaria del bucket de ubicación de salida. Se trata de una medida de seguridad añadida. Si el ID de cuenta del propietario del bucket no coincide con el ID que se especifique aquí, los intentos de generar el bucket fallarán. Para obtener información detallada, consulte Verificación de la propiedad del bucket con la condición de propietario del bucket en la Guía del usuario de Amazon S3.

   nota

   La configuración del propietario esperado del bucket se aplica solo a la ubicación de salida de Amazon S3 especificada para los resultados de las consultas de Athena. No se aplica a otras ubicaciones de Amazon S3, como las ubicaciones de origen de datos en buckets externos de Amazon S3, ubicaciones de tablas de destino de CTAS y INSERT INTO, ubicaciones de salida de instrucciones UNLOAD, operaciones para desbordar buckets para consultas federadas, o consultas SELECT ejecutadas en una tabla de otra cuenta.

7. (Opcional) Elija Encrypt query results (Cifrar los resultados de las consultas) si desea cifrar los resultados de las consultas almacenados en Simple Storage Service (Amazon S3). Para obtener más información sobre el cifrado en Athena, consulte Cifrado en reposo.

8. (Opcional) Elija Assign bucket owner full control over query results (Asignar control total sobre los resultados de las consultas al propietario del bucket) para conceder acceso de control total sobre los resultados de las consultas al propietario del bucket cuando estén habilitadas las ACL para el bucket de resultados de las consultas. Por ejemplo, si la ubicación del resultado de las consultas es propiedad de otra cuenta, puede conceder la propiedad y el control total sobre los resultados de las consultas a la otra cuenta.

   Si la configuración de propiedad de objetos de S3 del bucket es Bucket owner preferred (Propietario del bucket preferido), el propietario del bucket también es propietario de todos los objetos de resultados de las consultas escritos desde este grupo de trabajo. Por ejemplo, si el grupo de trabajo de una cuenta externa habilita esta opción y establece la ubicación del resultado de la consulta en el bucket de Simple Storage Service (Amazon S3) de la cuenta que tiene Bucket owner preferred (Propietario del bucket preferido) como configuración de propiedad de objetos de S3, usted es propietario de los resultados de las consultas del grupo de trabajo externo y tiene control total sobre ellos.

   Seleccionar esta opción cuando la configuración de la propiedad de objetos S3 del bucket de resultados de las consultas es Bucket owner enforced (Propietario del bucket obligatorio) no surte ningún efecto. Para obtener más información, consulte Control de la propiedad de los objetos y desactivación de las ACL del bucket en la Guía del usuario de Simple Storage Service (Amazon S3).

9. Si quiere solicitar a todos los usuarios del grupo de trabajo que utilicen la ubicación de los resultados de la consulta especificada, desplácese hacia abajo hasta la sección Settings (Configuración) y seleccione Override client-side settings (Invalidar la configuración del lado del cliente).

10. Elija Guardar cambios.

Descarga de archivos de resultados de consultas mediante la consola de Athena

Puede descargar el archivo CSV de resultados de la consulta desde el panel de consultas, inmediatamente después de ejecutar una consulta. También puede descargar los resultados de las consultas recientes de la pestaña Recent queries (Consultas recientes).

nota

Los archivos de resultados de la consulta de Athena son archivos de datos que contienen información que los usuarios pueden configurar. Algunos programas que se utilizan para leer y analizar esta información podrían interpretar estos datos como comandos (inyección CSV). Por este motivo, al importar datos de CSV de resultados de consulta a un programa de hoja de cálculo, este programa podría advertirle acerca de problemas de seguridad. Para mantener el sistema seguro, siempre debe optar por desactivar enlaces o macros de los resultados de consulta descargados.

Para ejecutar una consulta y descargar los resultados de la consulta

1. Ingrese la consulta en el editor de consultas y, a continuación, elija Run (Ejecutar).

   Cuando la consulta termina de ejecutarse, el panel Results (Resultados) muestra los resultados de la consulta.

2. Para descargar un archivo CSV de los resultados de la consulta, elija Download results (Descargar resultados) encima del panel de resultados de la consulta. En función del navegador y su configuración, es posible que tenga que confirmar la descarga.

   

Para descargar un archivo de resultados de consulta para una consulta anterior

1. Elija Recent queries (Consultas recientes).

   

2. Utilice el cuadro de búsqueda para encontrar la consulta, seleccione la consulta y, a continuación, elija Download results (Descargar resultados).

   nota

   No se puede utilizar la opción Download results (Descargar resultados) para recuperar resultados de consultas que se hayan eliminado manualmente, ni recuperar resultados de consultas que se hayan eliminado o movido a otra ubicación debido a reglas del ciclo de vida de Amazon S3.

   

Vista de consultas recientes

Puede utilizar la consola de Athena para ver qué consultas se hicieron correctamente o no pudieron hacerse y ver los detalles de error de las consultas que no pudieron hacerse. Athena conserva el historial de consultas durante 45 días.

Para ver las consultas recientes en la consola de Athena

1. Abra la consola de Athena en https://console.aws.amazon.com/athena/.

2. Elija Recent queries (Consultas recientes). En la pestaña Recent queries (Consultas recientes) se muestra información sobre cada consulta ejecutada.

3. Para abrir una instrucción de consulta en el editor de consultas, elija el ID de ejecución de la consulta.

   

4. Para ver los detalles de una consulta que ha producido un error, elija el enlace Failed (Error) de la consulta.

   

Descarga de varias consultas recientes a un archivo CSV

Puede utilizar la pestaña Recent queries (Consultas recientes) de la consola de Athena para exportar una o más consultas recientes a un archivo CSV para verlas en formato tabular. El archivo descargado no contiene los resultados de la consulta, sino la cadena de consulta SQL propiamente dicha y otra información sobre la consulta. Los campos exportados incluyen el ID de ejecución, el contenido de la cadena de consulta, la hora de inicio de la consulta, el estado, el tiempo de ejecución, la cantidad de datos escaneados, la versión del motor de consultas utilizada y el método de cifrado. Puede exportar un máximo de 500 consultas recientes o un máximo filtrado de 500 consultas mediante los criterios que introduzca en el cuadro de búsqueda.

Para exportar una o más consultas recientes a un archivo CSV

1. Abra la consola de Athena en https://console.aws.amazon.com/athena/.

2. Elija Recent queries (Consultas recientes).

3. (Opcional) Utilice el cuadro de búsqueda para filtrar las consultas recientes que desea descargar.

4. Elija Download CSV (Descargar CSV).

   

5. Cuando aparezca el mensaje para guardar el archivo, seleccione Save (Guardar). El nombre de archivo predeterminado es Recent Queries seguido de una marca de tiempo (por ejemplo, Recent Queries 2022-12-05T16 04 27.352-08 00.csv).

Configuración de las opciones de visualización de consultas recientes

Puede configurar las opciones de la pestaña Recent queries (Consultas recientes) como las columnas que mostrar y el ajuste de texto.

Para configurar las opciones de la pestaña Recent queries (Consultas recientes)

1. Abra la consola de Athena en https://console.aws.amazon.com/athena/.

2. Elija Recent queries (Consultas recientes).

3. Seleccione el botón de opciones (icono con forma de engranaje).

   

4. En el cuadro de diálogo Preferences (Preferencias), elija el número de filas por página, el comportamiento del ajuste de líneas y las columnas que mostrar.

   

5. Elija Confirmar.

Mantener el historial de consultas durante más de 45 días

Si desea mantener el historial de consultas durante más de 45 días, puede recuperarlo y guardarlo en un almacén de datos como Amazon S3. Para automatizar este proceso, puede usar acciones de la API y comandos de la CLI de Athena y Amazon S3. En el siguiente procedimiento se resumen estos pasos.

Para recuperar y guardar el historial de consultas mediante programación

1. Utilice la acción de la API de Athena ListQueryExecutions o el comando de la CLI list-query-executions para recuperar los ID de consulta.

2. Utilice la acción de la API de Athena GetQueryExecution o el comando de la CLI get-query-execution para recuperar información sobre cada consulta en función de su ID.

3. Utilice la acción de la API de Amazon S3 PutObject o el comando de la CLI put-object para guardar la información en Amazon S3.

Búsqueda de archivos de salida de consulta en Amazon S3

Los archivos de salida de la consulta se almacenan en subcarpetas en Amazon S3 con el siguiente patrón de ruta, a menos que la consulta se produzca en un grupo de trabajo cuya configuración invalida la configuración del lado del cliente. Cuando la configuración del grupo de trabajo invalida la configuración del lado del cliente, la consulta utiliza la ruta de resultados especificada por el grupo de trabajo.

QueryResultsLocationInS3/[QueryName|Unsaved/yyyy/mm/dd/]

• QueryResultsLocationInS3 es la ubicación del resultado de la consulta especificada por la configuración del grupo de trabajo o la configuración del lado del cliente. Para obtener más información, consulte Especificación de una ubicación de resultados de consulta más adelante en este documento.

• Las siguientes subcarpetas se crean solo para las consultas ejecutadas desde la consola cuya ruta de resultados no ha sido invalidada por la configuración del grupo de trabajo. Las consultas que se ejecutan desde la AWS CLI o mediante la API de Athena se guardan directamente en QueryResultsLocationInS3.

  • QueryName es el nombre de la consulta cuyos resultados se guardan. Si la consulta se ejecutó pero no se guardó, se utiliza Unsaved.

  • aaaa/mm/dd es la fecha de ejecución de la consulta.

Los archivos asociados con una consulta CREATE TABLE AS SELECT se almacenan en una subcarpeta tables del patrón anterior.

Identificación de archivos de salida de consultas

Los archivos se guardan en la ubicación de resultados de las consultas de Amazon S3 en función del nombre, el ID y la fecha de ejecución de la consulta. A los archivos de cada consulta se les asigna nombre utilizando el QueryID, que es un identificador único que Athena asigna a cada consulta cuando se ejecuta.

Se guardan los siguientes tipos de archivos:

Tipo de archivo	Patrones de nomenclatura de archivos	Descripción
Archivos de resultados de consulta	QueryID.csv QueryID.txt	Los archivos de resultados de consulta DML se guardan en un formato de valores separados por comas (CSV). Los resultados de la consulta DDL se guardan como archivos de texto sin formato. Puede descargar los archivos de resultados desde el panel Results (Resultados) de la consola cuando utilice la consola o desde el historial de consultas. Para obtener más información, consulte Descarga de archivos de resultados de consultas mediante la consola de Athena.
Archivos de metadatos de consulta	QueryID.csv.metadata QueryID.txt.metadata	Los archivos de metadatos de consulta DML y DDL se guardan en formato binario y no son legibles por el usuario. La extensión del archivo corresponde al archivo de resultados de consulta relacionado. Athena utiliza los metadatos al leer los resultados de la consulta mediante la acción GetQueryResults. Aunque estos archivos se pueden eliminar, no lo recomendamos porque se pierde información importante sobre la consulta.
Archivos de manifiesto de datos	QueryID-manifest.csv	Los archivos de manifiesto de datos se generan para realizar un seguimiento de los archivos que Athena crea en las ubicaciones de origen de datos de Amazon S3 cuando se ejecuta una consulta INSERT INTO. Si se produce un error en una consulta, el manifiesto también realiza un seguimiento de los archivos que la consulta pretendía escribir. El manifiesto resulta útil para identificar los archivos que se quedaron huérfanos tras una consulta fallida.

Identificación de la ubicación de salida y los archivos de resultados de la consulta con la AWS CLI

Para utilizar la AWS CLI para identificar la ubicación de salida y los archivos de resultados de la consulta, ejecute el comando aws athena get-query-execution, como se muestra en el siguiente ejemplo. Sustituya abc1234d-5efg-67hi-jklm-89n0op12qr34 por el ID de la consulta.

aws athena get-query-execution --query-execution-id abc1234d-5efg-67hi-jklm-89n0op12qr34

El comando devuelve un resultado similar al siguiente. Para ver una descripción de cada parámetro de salida, consulte get-query-execution en la Referencia de comandos de la AWS CLI.

{
    "QueryExecution": {
        "Status": {
            "SubmissionDateTime": 1565649050.175,
            "State": "SUCCEEDED",
            "CompletionDateTime": 1565649056.6229999
        },
        "Statistics": {
            "DataScannedInBytes": 5944497,
            "DataManifestLocation": "s3://DOC-EXAMPLE-BUCKET/athena-query-results-123456789012-us-west-1/MyInsertQuery/2019/08/12/abc1234d-5efg-67hi-jklm-89n0op12qr34-manifest.csv",
            "EngineExecutionTimeInMillis": 5209
        },
        "ResultConfiguration": {
            "EncryptionConfiguration": {
                "EncryptionOption": "SSE_S3"
            },
            "OutputLocation": "s3://DOC-EXAMPLE-BUCKET/athena-query-results-123456789012-us-west-1/MyInsertQuery/2019/08/12/abc1234d-5efg-67hi-jklm-89n0op12qr34"
        },
        "QueryExecutionId": "abc1234d-5efg-67hi-jklm-89n0op12qr34",
        "QueryExecutionContext": {},
        "Query": "INSERT INTO mydb.elb_log_backup SELECT * FROM mydb.elb_logs LIMIT 100",
        "StatementType": "DML",
        "WorkGroup": "primary"
    }
}