O Amazon Redshift não permitirá mais a criação de UDFs do Python a partir do Patch 198. As UDFs do Python existentes continuarão a funcionar normalmente até 30 de junho de 2026. Para ter mais informações, consulte a [publicação de blog ](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/).
# Consultas programadas com o Editor de Consultas v2
Com o Editor de Consultas V2 do Amazon Redshift, é possível automatizar consultas SQL para que sejam executadas de acordo com uma programação. Consultas programadas são instruções SQL que são executadas automaticamente em horários ou intervalos específicos, o que permite que você gerencie com eficiência operações de dados e tarefas de analytics recorrentes. A programação de consultas é recomendável se você estiver pretendendo agilizar o processamento em lote, gerar relatórios regulares ou manter pipelines de dados em seu ambiente do Amazon Redshift.
As consultas programadas facilitam a automatização de fluxos de trabalho de extração, transformação e carregamento (ETL), atualizam painéis com insights atualizados e operacionalizam várias rotinas de gerenciamento de dados. As páginas a seguir detalham o processo de criação, configuração e gerenciamento de consultas programadas para otimizar workloads do Amazon Redshift.
# Criar uma programação de consultas com o Editor de Consultas v2
É possível criar uma programação para executar uma instrução SQL com o Editor de Consultas v2 do Amazon Redshift. Crie uma programação para executar sua instrução SQL nos intervalos de tempo que correspondam às suas necessidades de negócios. Na hora da execução da consulta programada, a consulta é iniciada pelo Amazon EventBridge e usa a API de dados do Amazon Redshift.
**Como criar uma programação a fim de executar uma instrução SQL**
1. Na visualização ![\[Editor\]](http://docs.aws.amazon.com/pt_br/redshift/latest/mgmt/images/qev2-align-left.png) do **Editor**, selecione **Programar** ![\[Schedule\]](http://docs.aws.amazon.com/pt_br/redshift/latest/mgmt/images/qev2-calendar.png) para criar uma programação para executar uma instrução SQL.
1. Quando você define a programação, fornece as informações a seguir.
+ Um perfil do IAM que assume as permissões necessárias para executar a consulta. Esse perfil do IAM também está associado ao cluster ou grupo de trabalho.
+ Os valores de autenticação para AWS Secrets Manager ou credenciais temporárias para autorizar o acesso ao cluster ou grupo de trabalho. Esses métodos de autenticação são compatíveis com a API de dados. Para obter mais informações, consulte [Autenticar uma consulta programada](query-editor-v2-schedule-query-authentication.md).
+ O cluster ou grupo de trabalho em que o banco de dados reside.
+ O nome do banco de dados que contém os dados a serem consultados.
+ O nome da consulta programada e sua descrição. O editor de consultas v2 usa “QS2-” como prefixo do nome da consulta programada que você fornece. O editor de consultas v1 prefixa os nomes das consultas programadas com “QS-”.
+ A instrução SQL a ser executada de acordo com a programação.
+ A frequência de programação e opções de repetição ou um valor formatado cron que define a programação. Para obter mais informações, consulte [Expressões Cron](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html#CronExpressions), no *Guia do usuário do Amazon CloudWatch Events*.
+ Opcionalmente, você pode ativar as notificações comuns do Amazon SNS para monitorar a consulta programada. Talvez seja necessário confirmar o endereço de e-mail fornecido para a notificação do Amazon SNS. Verifique se recebeu um e-mail com um link para confirmar o endereço de e-mail da notificação do Amazon SNS. Para obter mais informações, consulte [Notificações de e-mail](https://docs.aws.amazon.com/sns/latest/dg/sns-email-notifications.html) no *Guia do desenvolvedor do Amazon Simple Notification Service*. Se a consulta estiver sendo executada, mas você não vir mensagens publicadas no tópico do SNS, consulte [Minha regra é executada, mas eu não vejo nenhuma mensagem publicada no meu tópico do Amazon SNS](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-troubleshooting.html#eb-no-messages-published-sns) no *Guia do usuário do Amazon EventBridge*.
1. Escolha **Programar consulta** para salvar e ativar a programação e adicionar a programação à lista de consultas na visualização **Consultas programadas**.
As visualização de ![\[Scheduled queries\]](http://docs.aws.amazon.com/pt_br/redshift/latest/mgmt/images/qev2-calendar.png) de **Consultas programadas** lista todas as consultas programadas para os clusters e grupos de trabalho. Com essa visualização, é possível exibir detalhes da consulta de programação, ativar ou desativar a programação, editar a programação e excluir a consulta programada. Ao visualizar os detalhes da consulta, você também pode ver o histórico de execução da consulta com a programação.
**nota**
A execução de uma consulta programada só está disponível na lista **Histórico de programação** por 24 horas. As consultas executadas de acordo com uma programação não aparecem na visualização **Histórico de consultas** do editor de consultas v2.
## Demonstração do agendamento de uma consulta
Para ver uma demonstração de como agendar uma consulta, assista ao vídeo a seguir.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/gTw0XUpO8sw)
# Configurar permissões para programar uma consulta
Para programar consultas, o usuário do AWS Identity and Access Management (IAM) que define a programação e o perfil do IAM associado à programação devem ser configurados com as permissões do IAM para usar o Amazon EventBridge e a API de dados do Amazon Redshift. Para receber e-mails de consultas programadas, a notificação do Amazon SNS que você especificar opcionalmente também deverá ser configurada.
A seguir, descrevemos as tarefas para usar políticas gerenciadas da AWS para fornecer permissão, mas, dependendo do ambiente, talvez você queira reduzir as permissões concedidas.
Para o usuário do IAM conectado ao editor de consultas v2, edite o usuário do IAM que usa o console do IAM ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)).
+ Além das permissões para executar as operações do Amazon Redshift e do editor de consultas v2, anexe as políticas gerenciadas `AmazonEventBridgeFullAccess` e `AmazonRedshiftDataFullAccess` da AWS a um usuário do IAM.
+ Uma alternativa é atribuir as permissões a um perfil e designá-lo ao usuário.
Anexe uma política com a permissão `sts:AssumeRole` ao ARN do recurso do perfil do IAM que você especificou ao definir a consulta agendada. Para obter mais informações sobre como assumir perfis, consulte [Concessão de permissões a um usuário para alternar funções](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_permissions-to-switch.html) no *Guia do usuário do IAM*.
O exemplo a seguir mostra uma política de permissão que assume o perfil do IAM `myRedshiftRole` na conta `123456789012`. O perfil do IAM `myRedshiftRole` também é o perfil anexado ao cluster ou grupo de trabalho em que a consulta programada é executada.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AssumeIAMRole",
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": [
"arn:aws:iam::123456789012:role/myRedshiftRole"
]
}
]
}
```
------
Atualize a política de confiança do perfil do IAM usado para programar a consulta a fim de permitir que o usuário do IAM a assuma.
```
{
"Sid": "AssumeRole",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:user/myIAMusername"
},
"Action": "sts:AssumeRole"
}
]
}
```
Para o perfil do IAM que você especifica para permitir a execução da consulta programada, edite o perfil do IAM usando o console do IAM ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)).
+ Anexe as políticas gerenciadas `AmazonRedshiftDataFullAccess` e `AmazonEventBridgeFullAccess` da AWS ao perfil do IAM. A política gerenciada `AmazonRedshiftDataFullAccess` só concede a permissão `redshift-serverless:GetCredentials` para grupos de trabalho do Redshift sem servidor marcados com a chave `RedshiftDataFullAccess`.
# Autenticar uma consulta programada
Ao programar uma consulta, você usa um dos métodos de autenticação a seguir quando o SQL é executado. Cada método requer uma combinação diferente de entrada no editor de consultas v2. Esses métodos de autenticação são compatíveis com a API de dados, que é usada para executar as instruções SQL.
O usuário ou perfil do banco de dados usado para executar a consulta deve ter os privilégios de banco de dados necessários. Por exemplo, para conceder privilégios `IAMR:MyRedshiftQEv2Scheduler` à tabela `mytable`, execute o comando SQL a seguir.
```
GRANT all ON TABLE mytable TO "IAMR:MyRedshiftQEv2Scheduler";
```
Para ver a lista de usuários do banco de dados no cluster ou grupo de trabalho, consulte a visualização do sistema `PG_USER_INFO`.
**nota**
Todos os grupos de trabalho do Redshift sem servidor para o qual você programa consultas devem ser marcados com a chave `RedshiftDataFullAccess`. Para obter mais informações, consulte [Autorizar acesso à API de dados do Amazon Redshift](data-api-access.md).
Como alternativa à marcação do grupo de trabalho, você pode adicionar uma política em linha ao perfil do IAM (especificado com a programação) que permite `redshift-serverless:GetCredentials`. Por exemplo:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "UseTemporaryCredentialsForAllServerlessWorkgroups",
"Effect": "Allow",
"Action": "redshift-serverless:GetCredentials",
"Resource": [
"arn:aws:redshift-serverless:*:*:workgroup/*"
]
}
]
}
```
**AWS Secrets Manager**
Com este método, forneça um valor secreto para **secret-arn** que é armazenado no AWS Secrets Manager. Este segredo contém credenciais para se conectar ao seu banco de dados. Talvez você tenha criado um segredo com as credenciais adequadas quando criou o cluster ou o grupo de trabalho. O segredo deve ser marcado com a chave `RedshiftDataFullAccess`. Se a chave da tag ainda não estiver presente, use o console AWS Secrets Manager para adicioná-la. Para obter informações sobre como criar um segredo, consulte [Criar um segredo para credenciais de conexão de banco de dados](redshift-secrets-manager-integration-create.md).
Para obter mais informações sobre as permissões mínimas, consulte [Criação e gerenciamento de segredos com o AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html) no *Manual do usuário do AWS Secrets Manager*.
**Credenciais temporárias**
Com esse método, forneça o **Nome do banco de dados** e os valores do **Usuário do banco de dados** ao se conectar a um banco de dados em um cluster. Você só precisa fornecer o **Nome do banco de dados** ao se conectar a um banco de dados em um grupo de trabalho.
Ao se conectar a um cluster, a política `AmazonRedshiftDataFullAccess` concede ao usuário do banco de dados chamado `redshift_data_api_user` permissão para `redshift:GetClusterCredentials`. Se você quiser usar um usuário de banco de dados diferente para executar a instrução SQL, adicione uma política ao perfil do IAM anexado ao cluster para permitir `redshift:GetClusterCredentials`. O exemplo a seguir permite usuários do banco de dados `awsuser` e `myuser`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "UseTemporaryCredentialsForAllDbUsers",
"Effect": "Allow",
"Action": "redshift:GetClusterCredentials",
"Resource": [
"arn:aws:redshift:*:*:dbuser:*/awsuser",
"arn:aws:redshift:*:*:dbuser:*/myuser"
]
}
]
}
```
# Configurar permissões para consultar o histórico de consultas programadas
Para permitir que os usuários visualizem o histórico de consultas programadas, edite o perfil do IAM **Relações de confiança** (especificado com a programação) para adicionar permissões.
Veja a seguir um exemplo de política de confiança em um perfil do IAM que permite ao usuário do IAM *myIAMusername* ver o histórico de consultas programadas. Em vez de conceder a um usuário do IAM a permissão `sts:AssumeRole`, é possível optar por atribuir essa permissão a um perfil do IAM.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"redshift.amazonaws.com",
"redshift-serverless.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
},
{
"Effect": "Allow",
"Principal": {
"Service": "events.amazonaws.com"
},
"Action": "sts:AssumeRole"
},
{
"Sid": "AssumeRole",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:user/myIAMusername"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
# Monitoramento da consulta programada
Para o tópico do Amazon SNS que você especifica para enviar notificações por e-mail, crie o tópico do Amazon SNS usando o editor de consultas v2. Para isso, você deve acessar a seção **Notificações do SNS**, **Ativar** o monitoramento e criar o tópico com **Criar tópico do SNS**. O editor de consultas v2 cria o tópico do Amazon SNS e adiciona uma entidade principal de serviço à política de acesso do Amazon EventBridge. Veja a seguir uma **Política de acesso** de exemplo que é criada no tópico do Amazon SNS. No exemplo, são usados a Região da AWS *us-west-2*, a Conta da AWS *123456789012* e o tópico do Amazon SNS *select-version-pdx-testunload*.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "__default_policy_ID",
"Statement": [
{
"Sid": "Allow_Publish_Events",
"Effect": "Allow",
"Principal": {
"Service": "events.amazonaws.com"
},
"Action": "sns:Publish",
"Resource": "arn:aws:sns:us-west-2:123456789012:select-version-pdx-testunload"
}
]
}
```
------
Quando a consulta programada é executada, o Amazon SNS envia e-mails de notificação da AWS. O exemplo a seguir mostra um e-mail enviado para *myemail@example.com* referente à consulta programada *QS2-may25a* executada na Região da AWS *eu-north-1* na Conta da AWS *123.456.789.012* usando o tópico de notificação do Amazon SNS *may25a-SNS*.
```
{"version":"0","id":"8e4323ec-5258-7138-181b-91290e30ff9b","detail-type":"Scheduled Event","source":"aws.events","account":"123456789012","time":"2023-05-25T15:22:00Z",
"region":"eu-north-1","resources":["arn:aws:events:eu-north-1:123456789012:rule/QS2-may25a"],"detail":{}}
--
If you wish to stop receiving notifications from this topic, please click or visit the link below to unsubscribe:
https://sns.eu-north-1.amazonaws.com/unsubscribe.html?SubscriptionArn=arn:aws:sns:eu-north-1:123456789012:may25a-SNS:0c1a3d05-39c2-4507-bc3d-47250513d7b0&Endpoint=myemail@example.com
Please do not reply directly to this email. If you have any questions or comments regarding this email, please contact us at https://aws.amazon.com/support
```
# Solução de problemas da configuração de programação de uma consulta
Considere o seguinte se você tiver problemas ao programar uma consulta:
**As consultas não são executadas**
Verifique se o perfil do IAM usado na programação tem permissão para obter as credenciais temporárias do cluster. A permissão para clusters provisionados é `redshift:GetClusterCredentialsWithIAM`. A permissão para grupos de trabalho do Redshift sem servidor é `redshift-serverless:GetCredentials`.
**O histórico de programação não é exibido**
O usuário do IAM ou o perfil do IAM usado para fazer login no console da AWS não foi adicionado à política de confiança do perfil do IAM usado para programar a consulta.
Ao usar o AWS Secrets Manager para a consulta agendada para se conectar, confirme se o segredo está marcado com a chave `RedshiftDataFullAccess`.
Se a consulta agendada estiver usando uma conexão do AWS Secrets Manager, o perfil do IAM usado para agendar a consulta deverá ter o valor equivalente à política gerenciada `SecretsManagerReadWrite` anexada ao perfil.
**O status do histórico de consultas é `Failed`**
Exiba a visualização do sistema SYS\$1QUERY\$1HISTORY para obter detalhes sobre por que a consulta falhou. Um problema comum é que o usuário ou o perfil do banco de dados que foi usado para executar a consulta pode não ter o privilégio necessário para executar o SQL. Para obter mais informações, consulte [Autenticar uma consulta programada](query-editor-v2-schedule-query-authentication.md).
O SQL a seguir consulta a visualização SYS\$1QUERY\$1HISTORY para retornar consultas com falha.
```
SELECT user_id, query_id, transaction_id, session_id, database_name, query_type, status, error_message, query_text
FROM sys_query_history
WHERE status = 'failed';
```
Para descobrir detalhes de uma consulta programada com falha específica, consulte [Visualizar os resultados de uma consulta programada com o AWS CloudShell](query-editor-v2-schedule-query-troubleshooting-cloudshell.md).
# Visualizar os resultados de uma consulta programada com o AWS CloudShell
É possível usar o AWS CloudShell para descobrir detalhes sobre uma consulta programada. Você deve ter as permissões adequadas para executar os comandos da AWS CLI mostrados no procedimento a seguir.
**Para visualizar os resultados de uma consulta programada**
1. No console do AWS, abra o prompt de comando do AWS CloudShell. Para obter mais informações sobre o AWS CloudShell, consulte [O que é o AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html) no *Guia do usuário do AWS CloudShell*.
1. Assuma o perfil do IAM da consulta programada. Para assumir o perfil, encontre o perfil do IAM associado à consulta programada no editor de consultas v2 e use-o no comando da AWS CLI no AWS CloudShell. Por exemplo, para o perfil `scheduler`, insira um comando AWS STS para assumir o perfil usado pela consulta programada.
```
aws sts assume-role --role-arn "arn:aws:iam::123456789012:role/scheduler" --role-session-name "scheduler-test"
```
As credenciais retornadas são semelhantes às seguintes:
```
"Credentials": {
"AccessKeyId": "AKIAIOSFODNN7EXAMPLE",
"SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"SessionToken": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY...",
"Expiration": "2023-08-18T18:19:44+00:00"
},
"AssumedRoleUser": {
"AssumedRoleId": "AROA35B2NH6WBTP7ONL4E:scheduler-test",
"Arn": "arn:aws:sts::123456789012:assumed-role/scheduler/scheduler-test"
}
}
```
1. Crie variáveis de ambiente na AWS CLI usando as credenciais exibidas ao assumir o perfil do IAM. É necessário usar esses tokens antes do respectivo prazo de validade. Por exemplo, insira o seguinte no AWS CloudShell.
```
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY...
```
1. Para ver o erro de uma consulta com falha, execute o comando da AWS CLI para descrever uma instrução. O ID da instrução SQL é do **ID** mostrado na seção **Histórico de programação** de uma consulta programada no editor de consultas v2.
```
aws redshift-data describe-statement --id 130d2620-05d2-439c-b7cf-815d9767f513
```
Neste exemplo, o SQL programado `select * from users limit 100` resulta em um erro de SQL segundo o qual a tabela `users` não existe.
```
{
"CreatedAt": "2023-08-18T17:39:15.563000+00:00",
"Duration": -1,
"Error": "ERROR: relation \"users\" does not exist",
"HasResultSet": false,
"Id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"QueryString": "select * from users limit 100\n—RequestID=a1b2c3d4-5678-90ab-cdef-EXAMPLE22222; TraceID=1-633c5642-4039308d03f3a0ba53dbdf6f",
"RedshiftPid": 1073766651,
"RedshiftQueryId": 0,
"ResultRows": -1,
"ResultSize": -1,
"Status": "FAILED",
"UpdatedAt": "2023-08-18T17:39:16.116000+00:00",
"WorkgroupName": "default"
}
```