Para obtener capacidades similares a las de Amazon Timestream, considere Amazon Timestream LiveAnalytics para InfluxDB. Ofrece una ingesta de datos simplificada y tiempos de respuesta a las consultas en milisegundos de un solo dígito para realizar análisis en tiempo real. Obtenga más información [aquí](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html). Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Query `Query` es una operación sincrónica que le permite ejecutar una consulta sobre sus datos de Amazon Timestream. Si la habilitó `QueryInsights`, esta API también muestra información y métricas relacionadas con la consulta que ejecutó. `QueryInsights` ayuda a ajustar el rendimiento de la consulta. Para obtener más información sobre `QueryInsights`, consulte [Uso de la información sobre las consultas para su optimización en Amazon Timestream](https://docs.aws.amazon.com/timestream/latest/developerguide/using-query-insights.html). **nota** La cantidad máxima de solicitudes a la API de `Query` que puede realizar con la opción `QueryInsights` habilitada es de 1 consulta por segundo (QPS). Si supera esta tasa de consultas, es posible que se produzca una limitación. `Query` se desconectará después de 60 segundos. Debe actualizar el tiempo de espera predeterminado en el SDK para que admita un tiempo de espera de 60 segundos. Consulte el [Ejemplo de código](https://docs.aws.amazon.com/timestream/latest/developerguide/code-samples.run-query.html) para obtener más detalles. La solicitud de consulta fallará en los casos que se encuentra a continuación: + Si envía una solicitud de `Query` con el mismo token de cliente fuera del periodo de idempotencia de 5 minutos. + Si envía una solicitud de `Query` con el mismo token de cliente, pero cambia otros parámetros, dentro del periodo de idempotencia de 5 minutos. + Si el tamaño de la fila (incluidos los metadatos de la consulta) supera 1 MB, la consulta fallará y mostrará el siguiente mensaje de error: `Query aborted as max page response size has been exceeded by the output result row` + Si el principal de IAM del iniciador de consultas y el lector de resultados no son iguales and/or , el iniciador de consultas y el lector de resultados no tienen la misma cadena de consulta en las solicitudes de consulta, la consulta fallará y se producirá un error. `Invalid pagination token` ## Sintaxis de la solicitud ``` { "ClientToken": "string", "MaxRows": number, "NextToken": "string", "QueryInsights": { "Mode": "string" }, "QueryString": "string" } ``` ## Parámetros de la solicitud Para obtener información sobre los parámetros comunes a todas las acciones, consulte [Parámetros comunes](CommonParameters.md). La solicitud acepta los siguientes datos en formato JSON. ** [ClientToken](#API_query_Query_RequestSyntax) ** Cadena única que distingue entre mayúsculas y minúsculas de hasta 64 caracteres ASCII que se especifica cuando se realiza una solicitud de `Query`. Si se brinda una `ClientToken`, la llamada a `Query` se vuelve *idempotente*. Esto significa que ejecutar la misma consulta de manera repetida producirá el mismo resultado. Es decir, hacer varias solicitudes de `Query` idénticas tiene el mismo efecto que realizar una sola solicitud. Cuando lo utilice `ClientToken` en una consulta, tenga en cuenta lo siguiente: + Si la API de consulta se crea sin un `ClientToken`, el SDK de consulta genera un `ClientToken` en su nombre. + Si la invocación de `Query` solo contiene el `ClientToken`, pero no incluye un `NextToken`, se supone que la invocación de la `Query` se trata de una nueva ejecución de consulta. + Si la invocación contiene `NextToken`, se supone que esa invocación específica es una invocación posterior de una llamada anterior a la API de consulta y se muestra un conjunto de resultados. + Transcurridas 4 horas, cualquier solicitud con la misma información `ClientToken` se considerará una solicitud nueva. Tipo: cadena Restricciones de longitud: longitud mínima de 32. Longitud máxima de 128. Obligatorio: no ** [MaxRows](#API_query_Query_RequestSyntax) ** La cantidad total de filas que se mostrarán en el resultado de `Query`. La ejecución inicial de `Query` con un valor `MaxRows` especificado mostrará el conjunto de resultados de la consulta en dos casos: + El tamaño del resultado es inferior a `1MB`. + La cantidad de filas del conjunto de resultados es inferior al valor de `maxRows`. De lo contrario, la invocación inicial de `Query` solo muestra un `NextToken`, que luego se puede utilizar en llamadas posteriores para obtener el conjunto de resultados. Para reanudar la paginación, proporcione el valor de `NextToken` en el comando posterior. Si el tamaño de la fila es grande (por ejemplo, una fila tiene muchas columnas), Timestream puede mostrar menos filas para evitar que el tamaño de la respuesta supere el límite de 1 MB. Si no se brinda `MaxRows`, Timestream enviará la cantidad de filas necesaria para cumplir con el límite de 1 MB. Tipo: entero Rango válido: valor mínimo de 1. Valor máximo de 1000. Obligatorio: no ** [NextToken](#API_query_Query_RequestSyntax) ** Un token de paginación que se utiliza para mostrar un conjunto de resultados. Cuando se invoca la API de `Query` mediante `NextToken`, se supone que esa invocación específica es una invocación posterior de una llamada anterior a la `Query` y se muestra un conjunto de resultados. Sin embargo, si la invocación de `Query` solo contiene el `ClientToken`, se supone que la invocación de la `Query` se trata de una nueva ejecución de consulta. Tenga en cuenta lo siguiente cuando lo utilice NextToken en una consulta: + Un token de paginación puede utilizarse para un máximo de cinco invocaciones de `Query` O durante un máximo de 1 hora, lo que ocurra primero. + Si se usa el mismo `NextToken`, se obtendrá el mismo conjunto de registros. Para seguir paginando el conjunto de resultados, debe utilizar el `nextToken` más reciente. + Supongamos que una invocación de `Query` muestra dos valores de `NextToken`, `TokenA` y `TokenB`. Si se utiliza `TokenB` en una invocación de `Query` posterior, se invalida `TokenA` y no se puede reutilizar. + Para solicitar un conjunto de resultados anterior de una consulta después de que se inicie la paginación, debe volver a invocar la API de consultas. + El último `NextToken` debe usarse para paginar hasta que se muestre `null`, momento en el que se debe utilizar un `NextToken` nuevo. + Si el principal de IAM del iniciador de la consulta y el lector de resultados no son iguales, el iniciador de and/or la consulta y el lector de resultados no tienen la misma cadena de consulta en las solicitudes de consulta, la consulta fallará y se generará un error. `Invalid pagination token` Tipo: cadena Limitaciones de longitud: longitud mínima de 1. La longitud máxima es de 2048 caracteres. Obligatorio: no ** [QueryInsights](#API_query_Query_RequestSyntax) ** Encapsula la configuración para habilitar una `QueryInsights`. La habilitación de `QueryInsights` muestra información y métricas además de los resultados de la consulta que ejecutó. Puede utilizar las `QueryInsights` para ajustar el rendimiento de sus consultas. Tipo: objeto [QueryInsights](API_query_QueryInsights.md) Obligatorio: no ** [QueryString](#API_query_Query_RequestSyntax) ** La consulta que ejecutará Timestream. Tipo: cadena Limitaciones de longitud: longitud mínima de 1. La longitud máxima es de 262144 caracteres. Obligatorio: sí ## Sintaxis de la respuesta ``` { "ColumnInfo": [ { "Name": "string", "Type": { "ArrayColumnInfo": "ColumnInfo", "RowColumnInfo": [ "ColumnInfo" ], "ScalarType": "string", "TimeSeriesMeasureValueColumnInfo": "ColumnInfo" } } ], "NextToken": "string", "QueryId": "string", "QueryInsightsResponse": { "OutputBytes": number, "OutputRows": number, "QuerySpatialCoverage": { "Max": { "PartitionKey": [ "string" ], "TableArn": "string", "Value": number } }, "QueryTableCount": number, "QueryTemporalRange": { "Max": { "TableArn": "string", "Value": number } }, "UnloadPartitionCount": number, "UnloadWrittenBytes": number, "UnloadWrittenRows": number }, "QueryStatus": { "CumulativeBytesMetered": number, "CumulativeBytesScanned": number, "ProgressPercentage": number }, "Rows": [ { "Data": [ { "ArrayValue": [ "Datum" ], "NullValue": boolean, "RowValue": "Row", "ScalarValue": "string", "TimeSeriesValue": [ { "Time": "string", "Value": "Datum" } ] } ] } ] } ``` ## Elementos de respuesta Si la acción se realiza correctamente, el servicio devuelve una respuesta HTTP 200. El servicio devuelve los datos siguientes en formato JSON. ** [ColumnInfo](#API_query_Query_ResponseSyntax) ** Los tipos de datos de la columna del conjunto de datos que se muestra. Tipo: matriz de objetos [ColumnInfo](API_query_ColumnInfo.md) ** [NextToken](#API_query_Query_ResponseSyntax) ** Un token de paginación que se puede volver a utilizar en una llamada de `Query` para obtener el siguiente conjunto de resultados. Tipo: cadena Limitaciones de longitud: longitud mínima de 1. La longitud máxima es de 2048 caracteres. ** [QueryId](#API_query_Query_ResponseSyntax) ** Un identificador único para la consulta determinada. Tipo: cadena Limitaciones de longitud: longitud mínima de 1. La longitud máxima es de 64. Patrón: `[a-zA-Z0-9]+` ** [QueryInsightsResponse](#API_query_Query_ResponseSyntax) ** Encapsula `QueryInsights` que contiene información y métricas relacionadas con la consulta que ejecutó. Tipo: objeto [QueryInsightsResponse](API_query_QueryInsightsResponse.md) ** [QueryStatus](#API_query_Query_ResponseSyntax) ** Información sobre el estado de la consulta, incluidos el progreso y los bytes que se escanearon. Tipo: objeto [QueryStatus](API_query_QueryStatus.md) ** [Rows](#API_query_Query_ResponseSyntax) ** Las filas del conjunto de resultados que muestra la consulta. Tipo: matriz de objetos [Row](API_query_Row.md) ## Errores Para obtener información acerca de los errores comunes a todas las acciones, consulte [Errores comunes](CommonErrors.md). ** AccessDeniedException ** No cuenta con los permisos necesarios para acceder a la configuración de la cuenta. Código de estado HTTP: 400 ** ConflictException ** No se pudo sondear los resultados de una consulta cancelada. Código de estado HTTP: 400 ** InternalServerException ** Se produjo un error de servidor interno al procesar la solicitud. Código de estado HTTP: 400 ** InvalidEndpointException ** El punto de conexión solicitado no es válido. Código de estado HTTP: 400 ** QueryExecutionException ** Timestream no pudo ejecutar la consulta de manera correcta. Código de estado HTTP: 400 ** ThrottlingException ** La solicitud se retrasó debido a una cantidad excesiva de solicitudes. Código de estado HTTP: 400 ** ValidationException ** Solicitud no válida o con formato incorrecto. Código de estado HTTP: 400 ## Véase también Para obtener más información sobre el uso de esta API en uno de los idiomas específicos AWS SDKs, consulta lo siguiente: + [AWS Interfaz de línea de comandos V2](https://docs.aws.amazon.com/goto/cli2/timestream-query-2018-11-01/Query) + [AWS SDK para .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/timestream-query-2018-11-01/Query) + [AWS SDK para C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/timestream-query-2018-11-01/Query) + [AWS SDK para Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/timestream-query-2018-11-01/Query) + [AWS SDK para Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/timestream-query-2018-11-01/Query) + [AWS SDK para JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/timestream-query-2018-11-01/Query) + [AWS SDK para Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/timestream-query-2018-11-01/Query) + [AWS SDK para PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/timestream-query-2018-11-01/Query) + [AWS SDK para Python](https://docs.aws.amazon.com/goto/boto3/timestream-query-2018-11-01/Query) + [AWS SDK para Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/timestream-query-2018-11-01/Query)