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í.
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.
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 produzcan limitaciones.
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 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
Querycon el mismo token de cliente fuera del periodo de idempotencia de 5 minutos. -
Si envía una solicitud de
Querycon 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 la entidad principal de IAM del iniciador de la consulta y el lector de resultados no son iguales o el iniciador de la consulta 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.
La solicitud acepta los siguientes datos en formato JSON.
- ClientToken
-
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 unaClientToken, la llamada aQueryse vuelve idempotente. Esto significa que ejecutar la misma consulta de manera repetida producirá el mismo resultado. Es decir, hacer varias solicitudes deQueryidénticas tiene el mismo efecto que realizar una sola solicitud. Cuando lo utiliceClientTokenen una consulta, tenga en cuenta lo siguiente:-
Si la API de consulta se crea sin un
ClientToken, el SDK de consulta genera unClientTokenen su nombre. -
Si la invocación de
Querysolo contiene elClientToken, pero no incluye unNextToken, se supone que la invocación de laQueryse 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. -
Después de 4 horas, cualquier solicitud con el mismo
ClientTokenes tratada como una nueva solicitud.
Tipo: cadena
Limitaciones de longitud: longitud mínima de 32 caracteres. Longitud máxima de 128.
Obligatorio: no
-
- MaxRows
-
La cantidad total de filas que se mostrarán en el resultado de
Query. La ejecución inicial deQuerycon un valorMaxRowsespecificado 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
Querysolo muestra unNextToken, que luego se puede utilizar en llamadas posteriores para obtener el conjunto de resultados. Para reanudar la paginación, proporcione el valor deNextTokenen 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: número entero
Rango válido: valor mínimo de 1. Valor máximo de 1000.
Obligatorio: no
-
- NextToken
-
Un token de paginación que se utiliza para mostrar un conjunto de resultados. Cuando se invoca la API de
QuerymedianteNextToken, se supone que esa invocación específica es una invocación posterior de una llamada anterior a laQueryy se muestra un conjunto de resultados. Sin embargo, si la invocación deQuerysolo contiene elClientToken, se supone que la invocación de laQueryse trata de una nueva ejecución de consulta.Tenga en cuenta lo siguiente cuando utilice NextToken en una consulta:
-
Un token de paginación puede utilizarse para un máximo de cinco invocaciones de
QueryO 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 elnextTokenmás reciente. -
Supongamos que una invocación de
Querymuestra dos valores deNextToken,TokenAyTokenB. Si se utilizaTokenBen una invocación deQueryposterior, se invalidaTokenAy 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
NextTokendebe usarse para paginar hasta que se muestrenull, momento en el que se debe utilizar unNextTokennuevo. -
Si la entidad principal de IAM del iniciador de la consulta y el lector de resultados no son iguales o el iniciador de la consulta 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.
Tipo: cadena
Limitaciones de longitud: longitud mínima de 1. La longitud máxima es de 2048 caracteres.
Obligatorio: no
-
- QueryInsights
-
Encapsula la configuración para habilitar una
QueryInsights.La habilitación de
QueryInsightsmuestra información y métricas además de los resultados de la consulta que ejecutó. Puede utilizar lasQueryInsightspara ajustar el rendimiento de sus consultas.Tipo: objeto QueryInsights
Obligatorio: no
- QueryString
-
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
-
Los tipos de datos de la columna del conjunto de datos que se muestra.
Tipo: matriz de objetos ColumnInfo
- NextToken
-
Un token de paginación que se puede volver a utilizar en una llamada de
Querypara 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
-
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
-
Encapsula
QueryInsightsque contiene información y métricas relacionadas con la consulta que ejecutó.Tipo: objeto QueryInsightsResponse
- QueryStatus
-
Información sobre el estado de la consulta, incluidos el progreso y los bytes que se escanearon.
Tipo: objeto QueryStatus
- Rows
-
Las filas del conjunto de resultados que muestra la consulta.
Tipo: matriz de objetos Row
Errores
Para obtener información acerca de los errores comunes a todas las acciones, consulte Errores comunes.
- 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 un SDK de AWS de un idioma específico, consulte:
