Query - Amazon Timestream
Sintaxis de la solicitudParámetros de la solicitudSintaxis de la respuestaElementos de respuestaErroresVéase también

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

Queryes una operación sincrónica que le permite ejecutar una consulta con sus datos de Amazon Timestream.

Si la habilitóQueryInsights, API también devuelve información y métricas relacionadas con la consulta que ejecutó. QueryInsightsayuda a ajustar el rendimiento de la consulta. Para obtener más informaciónQueryInsights, consulte Uso de la información de consultas para optimizar las consultas en Amazon Timestream.

nota

El número máximo de Query API solicitudes que puede realizar con la QueryInsights opción habilitada es de 1 consulta por segundo ()QPS. Si superas esta tasa de consultas, es posible que se produzcan limitaciones.

Queryse agotará el tiempo de espera 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 información.

La solicitud de consulta fallará en los siguientes casos:

  • Si envías una Query solicitud con el mismo token de cliente fuera del período de idempotencia de 5 minutos.

  • Si envías una Query solicitud con el mismo token de cliente, pero cambias otros parámetros, dentro del plazo 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 IAM principal 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 generará un Invalid pagination token error.

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 JSON formato.

ClientToken

Cadena única, que distingue entre mayúsculas y minúsculas, de hasta 64 ASCII caracteres que se especifica al realizar una Query solicitud. Si se proporciona a, la llamada se ClientToken vuelve Query idempotente. Esto significa que ejecutar la misma consulta repetidamente producirá el mismo resultado. En otras palabras, realizar varias Query solicitudes idénticas tiene el mismo efecto que realizar una sola solicitud. Cuando lo ClientToken utilices en una consulta, ten en cuenta lo siguiente:

  • Si API se crea una instancia de la consulta sin unClientToken, la consulta SDK genera un ClientToken en tu nombre.

  • Si la Query invocación solo contiene la, ClientToken pero no la incluyeNextToken, se supone que la invocación de Query es una nueva ejecución de consulta.

  • Si la invocación contieneNextToken, se supone que esa invocación en particular es una invocación posterior de una llamada anterior a la consulta y se devuelve un API conjunto de resultados.

  • Transcurridas 4 horas, cualquier solicitud con lo mismo ClientToken se trata como una nueva solicitud.

Tipo: cadena

Restricciones de longitud: longitud mínima de 32. Longitud máxima de 128.

Obligatorio: no

MaxRows

El número total de filas que se devolverán en la Query salida. La ejecución inicial Query con un MaxRows valor especificado devolverá el conjunto de resultados de la consulta en dos casos:

  • El tamaño del resultado es inferior a1MB.

  • El número de filas del conjunto de resultados es inferior al valor demaxRows.

De lo contrario, la invocación inicial de Query solo devuelve aNextToken, que luego se puede usar en llamadas posteriores para obtener el conjunto de resultados. Para reanudar la paginación, indique el NextToken valor en el comando siguiente.

Si el tamaño de la fila es grande (por ejemplo, una fila tiene muchas columnas), Timestream puede devolver menos filas para evitar que el tamaño de la respuesta supere el límite de 1 MB. Si no MaxRows se proporciona, Timestream enviará el número de filas necesario 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

Un token de paginación que se utiliza para devolver un conjunto de resultados. Cuando Query API se invoca utilizandoNextToken, se supone que esa invocación en particular es una invocación posterior de una llamada anterior aQuery, y se devuelve un conjunto de resultados. Sin embargo, si la Query invocación solo contiene elClientToken, se supone que la invocación de Query es una nueva ejecución de consulta.

Tenga en cuenta lo siguiente cuando se utilice NextToken en una consulta:

  • Un token de paginación se puede utilizar para un máximo de cinco Query invocaciones o durante un máximo de 1 hora, lo que ocurra primero.

  • Si lo usas, NextToken obtendrás el mismo conjunto de registros. Para seguir paginando el conjunto de resultados, debe utilizar el más reciente. nextToken

  • Supongamos que una Query invocación devuelve dos NextToken valores y. TokenA TokenB Si TokenB se usa en una Query invocación posterior, TokenA se invalida y no se puede reutilizar.

  • Para solicitar un conjunto de resultados anterior de una consulta una vez iniciada la paginación, debe volver a invocar la consulta. API

  • La última NextToken debe usarse para paginar hasta que se devuelva, momento en el que null se debe usar una nueva. NextToken

  • Si el IAM principio del iniciador de consultas 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 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

Encapsula la configuración para la activación. QueryInsights

La activación QueryInsights devuelve información y métricas además de los resultados de la consulta que ejecutó. Se puede utilizar QueryInsights para ajustar el rendimiento de las 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 de HTTP 200.

El servicio devuelve los siguientes datos en JSON formato.

ColumnInfo

Los tipos de datos de las columnas del conjunto de resultados devuelto.

Tipo: matriz de objetos ColumnInfo

NextToken

Un token de paginación que se puede volver a utilizar en una Query llamada 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

Un identificador único para la consulta dada.

Tipo: cadena

Limitaciones de longitud: longitud mínima de 1. La longitud máxima es de 64.

Patrón: [a-zA-Z0-9]+

QueryInsightsResponse

QueryInsightsEncapsula información y métricas relacionadas con la consulta que ejecutaste.

Tipo: objeto QueryInsightsResponse

QueryStatus

Información sobre el estado de la consulta, incluidos el progreso y los bytes escaneados.

Tipo: objeto QueryStatus

Rows

El conjunto de filas de resultados devueltas por 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 está autorizado a realizar esta acción.

HTTPCódigo de estado: 400

ConflictException

No se han podido sondear los resultados de una consulta cancelada.

HTTPCódigo de estado: 400

InternalServerException

El servicio no pudo procesar completamente esta solicitud debido a un error interno del servidor.

HTTPCódigo de estado: 400

InvalidEndpointException

El punto final solicitado no era válido.

HTTPCódigo de estado: 400

QueryExecutionException

Timestream no pudo ejecutar la consulta correctamente.

HTTPCódigo de estado: 400

ThrottlingException

La solicitud fue denegada debido a una limitación de la solicitud.

HTTPCódigo de estado: 400

ValidationException

Solicitud no válida o mal formada.

HTTPCódigo de estado: 400

Véase también

Para obtener más información sobre cómo usarlo API en uno de los idiomas específicos AWS SDKs, consulte lo siguiente: