ExecuteStatement - Hologres: Central de Documentação do Alibaba Cloud

Executa uma instrução SQL de forma síncrona em um banco de dados especificado via OpenAPI e retorna o resultado.

Descrição da operação

Use esta API para executar instruções SQL de forma segura em uma instância Hologres por meio da OpenAPI.

Antes de usar esta API, certifique-se de que os seguintes pré-requisitos sejam atendidos:

A opção "Permitir execução de SQL através da OpenAPI" está ativada na aba "Segurança de Dados" da página de detalhes da instância no console.
A conta RAM chamadora deve ter a permissão hologram:ExecuteStatement.

Esta API suporta instruções como SELECT, DDL e DML. Também suporta consultas parametrizadas com placeholders $1 e $2 para prevenir injeção de SQL. Por padrão, os resultados da consulta são limitados a 200 linhas (configurável até 1.000) e 10 MB. Conjuntos de resultados que excedem esses limites são truncados, e o campo truncated na resposta indica se o truncamento ocorreu. O timeout para uma única execução é de 30 segundos.

Experimente agora

Experimente esta API no OpenAPI Explorer, sem necessidade de assinatura manual. Chamadas bem-sucedidas geram automaticamente código SDK correspondente aos seus parâmetros. Faça o download com segurança de credenciais integrada para uso local.

Testar

Autorização RAM

Nenhuma autorização necessária para esta operação. Se você encontrar problemas com esta operação, entre em contato com o suporte técnico.

Sintaxe da solicitação

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

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
instanceId	string	Não	O ID da instância.	hgprecn-cn-i7m2ucpyu005

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
body	object	Não	O corpo da solicitação.
dbName	string	Não	O nome do banco de dados.	test_db
sql	string	Não	A instrução SQL a ser executada. O comprimento máximo é de 16.384 caracteres. Você pode especificar múltiplas instruções SQL separadas por ponto e vírgula. Se múltiplas instruções forem fornecidas, a API retorna o resultado da última instrução.	select * from test_table limit 10;
parameters	array	Não	Um array de parâmetros vinculados para uma consulta parametrizada. Esses parâmetros mapeiam sequencialmente para os placeholders (por exemplo, `$1`, `$2`) na instrução SQL. Os tipos suportados incluem `String`, `Long`, `Double`, `Boolean` e `null` (para SQL `NULL`). O uso de consultas parametrizadas ajuda a prevenir injeção de SQL e melhora a taxa de reutilização de cache para prepared statements. Esses parâmetros se aplicam a todas as instruções SQL no campo sql.
	any	Não	O valor de um parâmetro.	test_val
maxRows	integer	Não	O número máximo de linhas a retornar. Valor padrão: 200. Máximo: 1.000. Se o conjunto de resultados exceder esse limite, ele será truncado, conforme indicado pelo campo `Truncated` na resposta.	300
maxBytes	integer	Não	O tamanho máximo da resposta, em bytes. Valor padrão: 10.485.760 (10 MB). Se o tamanho da resposta exceder esse limite, ela será truncada, conforme indicado pelo campo Truncated na resposta.	1024
queryTimeout	integer	Não	O timeout da consulta, em segundos. Valor padrão: 30. Máximo: 30. Mínimo: 1. Se uma consulta exceder esse limite de tempo, o servidor a cancela.	5

Elementos de resposta

Elemento	Tipo	Descrição	Exemplo
	object	Os dados do resultado.
requestId	string	O ID da solicitação.	819A7F0F-2951-540F-BD94-6A41ECF0281F
success	string	Indica se a solicitação foi bem-sucedida.	True
errorCode	string	O código de erro. Este parâmetro é retornado apenas se a solicitação falhar.	InvalidParameterValue
errorMessage	string	A mensagem de erro. Este parâmetro é retornado apenas se a solicitação falhar.	参数值不合法（如 SQL 为空、超长等）
httpStatusCode	string	O código de status HTTP.	200
data	object	O resultado da execução da instrução SQL.
success	boolean	Indica se a instrução SQL foi executada com sucesso.
errorCode	string	O código de erro da execução da instrução SQL. Este parâmetro é retornado apenas se a execução falhar.	InvalidParameterValue
errorMessage	string	A mensagem de erro da execução da instrução SQL. Este parâmetro é retornado apenas se a execução falhar.	参数值不合法（如 SQL 为空、超长等）
results	array<object>	Uma lista de resultados de execução. Esta lista sempre contém exatamente um objeto de resultado. Se você executar múltiplas instruções SELECT, apenas o resultado da última será retornado.
	array<object>	Um objeto que contém o resultado de uma única instrução SQL.
success	boolean	Indicates whether the SQL statement was executed successfully.	True
sql	string	The executed SQL statement.	select * from test_table limit 10;
count	integer	The number of rows returned by a SELECT statement.	25
updateCount	integer	The number of rows affected by an INSERT, UPDATE, or DELETE statement. This parameter is not returned for SELECT statements.	10
truncated	boolean	Indicates whether the result set was truncated. The value is `true` if the number of returned rows exceeds the value of `MaxResults`.
queryId	string	The ID of the query.	E3F4B2A7-1234-5678-9ABC-DEF012345678
errorMessage	string	The error message for the SQL statement.	ERROR: relation \"non_existent_table\" does not exist\n Position: 15
errorCode	string	The error code for the SQL statement.	SQL_ERROR
columnMetadata	array<object>	The metadata of columns in the result set.
	object	An object that contains the metadata for a single column.
name	string	The name of the column.	id
type	string	The data type of the column, such as `int4`, `text`, or `bool`.	int4
nullable	boolean	Indicates whether the column can be null.
records	array	The set of records that are returned by the query. Each row is an array of strings, and all values are serialized as strings. A NULL value is represented as "\N".
	array	An array that represents a single row in the result set.
	string	A field value, returned as a string.	["1", "Alice"]

Exemplos

Resposta de sucesso

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 erro

Código de status HTTP	Código de erro	Mensagem de erro	Descrição
403	NoPermission	RAM user permission is insufficient, please grant AliyunHologresReadOnlyAccess permission.

Consulte Códigos de Erro para uma lista completa.

Notas de versão

Consulte Notas de Versão para uma lista completa.