ExecuteStatement - Hologres - Centro de documentación de Alibaba Cloud

Ejecuta una instrucción SQL de forma síncrona en una base de datos especificada a través de OpenAPI y devuelve el resultado.

Descripción de la operación

Utilice esta API para ejecutar instrucciones SQL de forma segura en una instancia de Hologres a través de OpenAPI.

Antes de utilizar esta API, asegúrese de cumplir con los siguientes requisitos previos:

La opción "Permitir ejecución de SQL a través de OpenAPI" está habilitada en la pestaña "Seguridad de datos" de la página de detalles de la instancia en la consola.
La cuenta RAM que realiza la llamada debe tener el permiso hologram:ExecuteStatement.

Esta API admite instrucciones como SELECT, DDL y DML. También admite consultas parametrizadas con marcadores de posición $1 y $2 para prevenir la inyección de SQL. De forma predeterminada, los resultados de las consultas están limitados a 200 filas (configurable hasta 1,000) y 10 MB. Los conjuntos de resultados que superan estos límites se truncan, y el campo truncated en la respuesta indica si ocurrió dicho truncamiento. El tiempo de espera para una sola ejecución es de 30 segundos.

Pruébelo ahora

Pruebe esta API en OpenAPI Explorer sin necesidad de firma manual. Las llamadas exitosas generan automáticamente código SDK acorde a sus parámetros. Descárguelo con seguridad de credenciales integrada para uso local.

Test

Autorización de RAM

No se requiere autorización para esta operación. Si experimenta problemas al ejecutarla, póngase en contacto con el soporte técnico.

Sintaxis de la solicitud

POST /api/v1/instances/{instanceId}/executeStatement HTTP/1.1

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción	Ejemplo
instanceId	string	No	El ID de la instancia.	hgprecn-cn-i7m2ucpyu005

Parámetros de la solicitud

Parámetro	Tipo	Obligatorio	Descripción	Ejemplo
body	object	No	El cuerpo de la solicitud.
dbName	string	No	El nombre de la base de datos.	test_db
sql	string	No	La instrucción SQL que se va a ejecutar. La longitud máxima es de 16,384 caracteres. Puede especificar varias instrucciones SQL separadas por punto y coma. Si se proporcionan varias instrucciones, la API devuelve el resultado de la última instrucción.	select * from test_table limit 10;
parameters	array	No	Una matriz de parámetros enlazados para una consulta parametrizada. Estos parámetros se asignan secuencialmente a los marcadores de posición (por ejemplo, `$1`, `$2`) en la instrucción SQL. Los tipos admitidos incluyen `String`, `Long`, `Double`, `Boolean` y `null` (para `NULL` de SQL). El uso de consultas parametrizadas ayuda a prevenir la inyección de SQL y mejora la tasa de reutilización de caché para instrucciones preparadas. Estos parámetros se aplican a todas las instrucciones SQL en el campo sql.
	any	No	El valor de un parámetro.	test_val
maxRows	integer	No	El número máximo de filas que se van a devolver. Valor predeterminado: 200. Máximo: 1,000. Si el conjunto de resultados supera este límite, se trunca, tal como lo indica el campo `Truncated` en la respuesta.	300
maxBytes	integer	No	El tamaño máximo de la respuesta, en bytes. Valor predeterminado: 10,485,760 (10 MB). Si el tamaño de la respuesta supera este límite, se trunca, tal como lo indica el campo Truncated en la respuesta.	1024
queryTimeout	integer	No	El tiempo de espera de la consulta, en segundos. Valor predeterminado: 30. Máximo: 30. Mínimo: 1. Si una consulta supera este límite de tiempo, el servidor la cancela.	5

Elementos de la respuesta

Elemento	Tipo	Descripción	Ejemplo
	object	Los datos del resultado.
requestId	string	El ID de la solicitud.	819A7F0F-2951-540F-BD94-6A41ECF0281F
success	string	Indica si la solicitud se realizó correctamente.	True
errorCode	string	El código de error. Este parámetro se devuelve solo si la solicitud falla.	InvalidParameterValue
errorMessage	string	El mensaje de error. Este parámetro se devuelve solo si la solicitud falla.	参数值不合法（如 SQL 为空、超长等）
httpStatusCode	string	El código de estado HTTP.	200
data	object	El resultado de la ejecución de la instrucción SQL.
success	boolean	Indica si la instrucción SQL se ejecutó correctamente.
errorCode	string	El código de error de la ejecución de la instrucción SQL. Este parámetro se devuelve solo si la ejecución falla.	InvalidParameterValue
errorMessage	string	El mensaje de error de la ejecución de la instrucción SQL. Este parámetro se devuelve solo si la ejecución falla.	参数值不合法（如 SQL 为空、超长等）
results	array<object>	Una lista de resultados de ejecución. Esta lista siempre contiene exactamente un objeto de resultado. Si ejecuta varias instrucciones SELECT, solo se devuelve el resultado de la última.
	array<object>	Un objeto que contiene el resultado de una sola instrucción SQL.
success	boolean	Indica si la instrucción SQL se ejecutó correctamente.	True
sql	string	La instrucción SQL ejecutada.	select * from test_table limit 10;
count	integer	El número de filas devueltas por una instrucción SELECT.	25
updateCount	integer	El número de filas afectadas por una instrucción INSERT, UPDATE o DELETE. Este parámetro no se devuelve para instrucciones SELECT.	10
truncated	boolean	Indica si el conjunto de resultados se truncó. El valor es `true` si el número de filas devueltas supera el valor de `MaxResults`.
queryId	string	El ID de la consulta.	E3F4B2A7-1234-5678-9ABC-DEF012345678
errorMessage	string	El mensaje de error de la instrucción SQL.	ERROR: relation \"non_existent_table\" does not exist\n Position: 15
errorCode	string	El código de error de la instrucción SQL.	SQL_ERROR
columnMetadata	array<object>	Los metadatos de las columnas en el conjunto de resultados.
	object	Un objeto que contiene los metadatos de una sola columna.
name	string	El nombre de la columna.	id
type	string	El tipo de datos de la columna, como `int4`, `text` o `bool`.	int4
nullable	boolean	Indica si la columna puede ser nula.
records	array	El conjunto de registros que devuelve la consulta. Cada fila es una matriz de cadenas y todos los valores se serializan como cadenas. Un valor NULL se representa como "\N".
	array	Una matriz que representa una sola fila en el conjunto de resultados.
	string	Un valor de campo, devuelto como una cadena.	["1", "Alice"]

Ejemplos

Respuesta exitosa

JSON Formato

{
  "requestId": "819A7F0F-2951-540F-BD94-6A41ECF0281F",
  "success": "True",
  "errorCode": "InvalidParameterValue",
  "errorMessage": "参数值不合法（如 SQL 为空、超长等）",
  "httpStatusCode": "200",
  "data": {
    "success": false,
    "errorCode": "InvalidParameterValue",
    "errorMessage": "参数值不合法（如 SQL 为空、超长等）",
    "results": [
      {
        "success": true,
        "sql": "select * from test_table limit 10;",
        "count": 25,
        "updateCount": 10,
        "truncated": false,
        "queryId": "E3F4B2A7-1234-5678-9ABC-DEF012345678",
        "errorMessage": "ERROR: relation \\\"non_existent_table\\\" does not exist\\n  Position: 15",
        "errorCode": "SQL_ERROR",
        "columnMetadata": [
          {
            "name": "id",
            "type": "int4",
            "nullable": false
          }
        ],
        "records": [
          [
            " [\"1\", \"Alice\"]"
          ]
        ]
      }
    ]
  }
}

Códigos de error

Código de estado HTTP	Código de error	Mensaje de error	Descripción
403	NoPermission	RAM user permission is insufficient, please grant AliyunHologresReadOnlyAccess permission.

Consulte Códigos de error para ver la lista completa.

Notas de la versión

Consulte Notas de la versión para ver la lista completa.