View a markdown version of this page

Passar instruções SQL para um data warehouse do Amazon Redshift - Amazon Redshift
Executar uma instrução SQLExecutar várias instruções SQLExecutar instruções com parâmetros

O Amazon Redshift deixará de oferecer suporte ao uso de UDFs em Python após 30 de junho de 2026. Começaremos a aplicar essa alteração em fases. Consulte mais informações sobre os detalhes do fim da vida útil do Python e as opções de migração na publicação do blog publicada em 30 de junho de 2025.

Passar instruções SQL para um data warehouse do Amazon Redshift

Os exemplos nesta página mostram maneiras diferentes de passar uma instrução SQL para o data warehouse.

Executar uma instrução SQL

Para executar uma instrução SQL, use o comando aws redshift-data execute-statement da AWS CLI.

O comando a seguir da AWS CLI executa uma instrução SQL em um cluster e retorna um identificador para obter os resultados. Este exemplo usa o método de autenticação AWS Secrets Manager.


aws redshift-data execute-statement 
    --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn 
    --cluster-identifier mycluster-test 
    --sql "select * from stl_query limit 1" 
    --database dev

Este é um exemplo da resposta.

{
    "ClusterIdentifier": "mycluster-test",
    "CreatedAt": 1598323175.823,
    "Database": "dev",
    "Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
    "SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}

O comando a seguir da AWS CLI executa uma instrução SQL em um cluster e retorna um identificador para obter os resultados. Este exemplo usa o método de autenticação de credenciais temporárias.


aws redshift-data execute-statement 
    --db-user myuser 
    --cluster-identifier mycluster-test 
    --database dev 
    --sql "select * from stl_query limit 1"

Este é um exemplo da resposta.

{
    "ClusterIdentifier": "mycluster-test",
    "CreatedAt": 1598306924.632,
    "Database": "dev",
    "DbUser": "myuser",
    "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}

O comando a seguir da AWS CLI executa uma instrução SQL em um grupo de trabalho com a tecnologia sem servidor e retorna um identificador para obter os resultados. Este exemplo usa o método de autenticação de credenciais temporárias.


aws redshift-data execute-statement 
    --database dev 
    --workgroup-name myworkgroup 
    --sql "select 1;"

Este é um exemplo da resposta.

{
 "CreatedAt": "2022-02-11T06:25:28.748000+00:00",
 "Database": "dev",
 "DbUser": "IAMR:RoleName",
 "Id": "89dd91f5-2d43-43d3-8461-f33aa093c41e",
 "WorkgroupName": "myworkgroup"
}

O comando a seguir da AWS CLI executa uma instrução SQL em um cluster e retorna um identificador para obter os resultados. Este exemplo usa o método de autenticação AWS Secrets Manager e um token de idempotência.


aws redshift-data execute-statement 
    --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn 
    --cluster-identifier mycluster-test 
    --sql "select * from stl_query limit 1" 
    --database dev 
    --client-token b855dced-259b-444c-bc7b-d3e8e33f94g1

Este é um exemplo da resposta.

{
    "ClusterIdentifier": "mycluster-test",
    "CreatedAt": 1598323175.823,
    "Database": "dev",
    "Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
    "SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}

Executar várias instruções SQL

Para executar várias instruções SQL com um comando, use o comando aws redshift-data batch-execute-statement da AWS CLI.

O comando a seguir da AWS CLI executa três instruções SQL em um cluster e retorna um identificador para obter os resultados. Este exemplo usa o método de autenticação de credenciais temporárias.


aws redshift-data batch-execute-statement 
    --db-user myuser 
    --cluster-identifier mycluster-test 
    --database dev 
    --sqls "set timezone to BST" "select * from mytable" "select * from another_table"

Este é um exemplo da resposta.

{
    "ClusterIdentifier": "mycluster-test",
    "CreatedAt": 1598306924.632,
    "Database": "dev",
    "DbUser": "myuser",
    "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}

Executar instruções com parâmetros

É possível usar parâmetros nomeados com as operações execute-statement e batch-execute-statement. Ao usar batch-execute-statement, os parâmetros são compartilhados entre todas as instruções SQL no lote. Cada instrução SQL pode referenciar um subconjunto dos parâmetros fornecidos, mas todo parâmetro deve ser utilizado por pelo menos uma instrução SQL.

O comando a seguir da AWS CLI executa uma instrução SQL em um cluster e retorna um identificador para obter os resultados. Este exemplo usa o método de autenticação AWS Secrets Manager. O texto SQL tem o parâmetro nomeado distance. Nesse caso, a distância usada no predicado é 5. Em uma instrução SELECT, os parâmetros nomeados para nomes de colunas só podem ser usados no predicado. Valores para parâmetros nomeados para a instrução SQL são especificados na opção parameters.


aws redshift-data execute-statement 
    --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn 
    --cluster-identifier mycluster-test 
    --sql "SELECT ratecode FROM demo_table WHERE trip_distance > :distance"  
    --parameters "[{\"name\": \"distance\", \"value\": \"5\"}]"
    --database dev

Este é um exemplo da resposta.

{
    "ClusterIdentifier": "mycluster-test",
    "CreatedAt": 1598323175.823,
    "Database": "dev",
    "Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
    "SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}

O exemplo a seguir usa a tabela EVENT do banco de dados de amostra. Para obter mais informações, consulte Tabela EVENT no Guia do desenvolvedor de banco de dados do Amazon Redshift.

Se você ainda não tem a tabela EVENT em seu banco de dados, você pode criar uma usando a API de dados da seguinte maneira:


aws redshift-data execute-statement 
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "create table event( eventid integer not null distkey, 
                           venueid smallint not null, 
                           catid smallint not null, 
                           dateid smallint not null sortkey, 
                           eventname varchar(200), 
                           starttime timestamp)"

O comando a seguir insere uma linha na tabela EVENT. 


aws redshift-data execute-statement 
--database dev
--cluster-id mycluster-test
--db-user awsuser 
--sql "insert into event values(:eventid, :venueid::smallint, :catid, :dateid, :eventname, :starttime)" 
--parameters "[{\"name\": \"eventid\", \"value\": \"1\"}, {\"name\": \"venueid\", \"value\": \"1\"}, 
               {\"name\": \"catid\", \"value\": \"1\"}, 
               {\"name\": \"dateid\", \"value\": \"1\"}, 
               {\"name\": \"eventname\", \"value\": \"event 1\"}, 
               {\"name\": \"starttime\", \"value\": \"2022-02-22\"}]"

O comando a seguir insere uma segunda linha na tabela EVENT. Este exemplo demonstra o seguinte:

  • O parâmetro chamado id é usado quatro vezes no texto SQL.

  • Conversão de tipo implícita é aplicada automaticamente ao inserir o parâmetro starttime.

  • A coluna venueid é o tipo de conversão para o tipo de dados SMALLINT.

  • As strings de caracteres que representam o tipo de dados DATE são implicitamente convertidas no tipo de dados TIMESTAMP.

  • Os comentários podem ser usados dentro do texto SQL.


aws redshift-data execute-statement 
--database dev
--cluster-id mycluster-test
--db-user awsuser 
--sql "insert into event values(:id, :id::smallint, :id, :id, :eventname, :starttime) /*this is comment, and it won't apply parameterization for :id, :eventname or :starttime here*/" 
--parameters "[{\"name\": \"eventname\", \"value\": \"event 2\"}, 
               {\"name\": \"starttime\", \"value\": \"2022-02-22\"}, 
               {\"name\": \"id\", \"value\": \"2\"}]"

O seguinte mostra as duas linhas inseridas:


 eventid | venueid | catid | dateid | eventname |      starttime
---------+---------+-------+--------+-----------+---------------------
       1 |       1 |     1 |      1 | event 1   | 2022-02-22 00:00:00
       2 |       2 |     2 |      2 | event 2   | 2022-02-22 00:00:00

O comando a seguir usa um parâmetro nomeado em uma cláusula WHERE para recuperar a linha em que eventid é 1. 


aws redshift-data execute-statement 
--database dev
--cluster-id mycluster-test
--db-user awsuser 
--sql "select * from event where eventid=:id"
--parameters "[{\"name\": \"id\", \"value\": \"1\"}]"

Execute o seguinte comando para obter os resultados SQL da instrução SQL anterior:


aws redshift-data get-statement-result --id 7529ad05-b905-4d71-9ec6-8b333836eb5a

Fornece os seguintes resultados:


{
    "Records": [
        [
            {
                "longValue": 1
            },
            {
                "longValue": 1
            },
            {
                "longValue": 1
            },
            {
                "longValue": 1
            },
            {
                "stringValue": "event 1"
            },
            {
                "stringValue": "2022-02-22 00:00:00.0"
            }
        ]
    ],
    "ColumnMetadata": [
        {
            "isCaseSensitive": false,
            "isCurrency": false,
            "isSigned": true,
            "label": "eventid",
            "length": 0,
            "name": "eventid",
            "nullable": 0,
            "precision": 10,
            "scale": 0,
            "schemaName": "public",
            "tableName": "event",
            "typeName": "int4"
        },
        {
            "isCaseSensitive": false,
            "isCurrency": false,
            "isSigned": true,
            "label": "venueid",
            "length": 0,
            "name": "venueid",
            "nullable": 0,
            "precision": 5,
            "scale": 0,
            "schemaName": "public",
            "tableName": "event",
            "typeName": "int2"
        },
        {
            "isCaseSensitive": false,
            "isCurrency": false,
            "isSigned": true,
            "label": "catid",
            "length": 0,
            "name": "catid",
            "nullable": 0,
            "precision": 5,
            "scale": 0,
            "schemaName": "public",
            "tableName": "event",
            "typeName": "int2"
        },
        {
            "isCaseSensitive": false,
            "isCurrency": false,
            "isSigned": true,
            "label": "dateid",
            "length": 0,
            "name": "dateid",
            "nullable": 0,
            "precision": 5,
            "scale": 0,
            "schemaName": "public",
            "tableName": "event",
            "typeName": "int2"
        },
        {
            "isCaseSensitive": true,
            "isCurrency": false,
            "isSigned": false,
            "label": "eventname",
            "length": 0,
            "name": "eventname",
            "nullable": 1,
            "precision": 200,
            "scale": 0,
            "schemaName": "public",
            "tableName": "event",
            "typeName": "varchar"
        },
        {
            "isCaseSensitive": false,
            "isCurrency": false,
            "isSigned": false,
            "label": "starttime",
            "length": 0,
            "name": "starttime",
            "nullable": 1,
            "precision": 29,
            "scale": 6,
            "schemaName": "public",
            "tableName": "event",
            "typeName": "timestamp"
        }
    ],
    "TotalNumRows": 1
}

O comando AWS CLI a seguir executa duas instruções SQL com parâmetros nomeados compartilhados em um cluster usando batch-execute-statement. O texto SQL nomeou parâmetros id e name. A primeira instrução SQL usa o parâmetro id e a segunda usa o parâmetro name.


aws redshift-data batch-execute-statement 
    --db-user myuser 
    --cluster-identifier mycluster-test 
    --database dev 
    --sqls "SELECT * FROM mytable WHERE id = :id" "SELECT * FROM mytable WHERE name = :name" 
    --parameters "[{\"name\": \"id\", \"value\": \"1\"},{\"name\": \"name\", \"value\": \"Alice\"}]"

Este é um exemplo da resposta.

{
    "ClusterIdentifier": "mycluster-test",
    "CreatedAt": 1598306924.632,
    "Database": "dev",
    "DbUser": "myuser",
    "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}

O comando AWS CLI a seguir executa duas instruções SQL em que o mesmo parâmetro é utilizado em ambas as instruções. O parâmetro chamado id é utilizado em uma instrução INSERT e em uma instrução SELECT.


aws redshift-data batch-execute-statement 
    --db-user myuser 
    --cluster-identifier mycluster-test 
    --database dev 
    --sqls "INSERT INTO mytable VALUES(:id, :name, :address)" "SELECT * FROM mytable WHERE id = :id" 
    --parameters "[{\"name\": \"id\", \"value\": \"1\"},{\"name\": \"name\", \"value\": \"Alice\"},{\"name\": \"address\", \"value\": \"Seattle\"}]"

Este é um exemplo da resposta.

{
    "ClusterIdentifier": "mycluster-test",
    "CreatedAt": 1598306924.632,
    "Database": "dev",
    "DbUser": "myuser",
    "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}