CREATE EXTERNAL SCHEMA - Amazon Redshift
SintaxeParâmetrosObservações de usoExemplos

CREATE EXTERNAL SCHEMA

Cria um novo esquema externo no banco de dados atual. Use esse esquema externo para se conectar a bancos de dados do Amazon RDS for PostgreSQL ou Amazon Aurora Edição compatível com PostgreSQL. Também é possível criar um esquema externo que faça referência a um banco de dados em um catálogo de dados externo, como AWS Glue, Athena ou um banco de dados em um metastore do Apache Hive, como Amazon EMR.

O proprietário deste esquema é o emissor do comando CREATE EXTERNAL SCHEMA. Para transferir a propriedade de um esquema externo, use ALTER SCHEMA para alterar o proprietário. Para conceder acesso ao esquema a outros usuários ou grupos de usuário, use o comando GRANT.

Você não pode usar os comandos GRANT ou REVOKE para permissões em uma tabela externa. Em vez disso, conceda ou revogue permissões no esquema externo.

nota

Se você tiver tabelas externas do Redshift Spectrum no catálogo de dados do Amazon Athena, poderá migrar o catálogo de dados do Athena para um AWS Glue Data Catalog. Para usar o catálogo de dados do AWS Glue com o Redshift Spectrum, talvez seja necessário alterar as políticas do AWS Identity and Access Management (IAM). Para obter mais informações, consulte Atualizar para o catálogo de dados do AWS Glue no Manual do usuário do Athena.

Para visualizar detalhes dos esquemas externos, consulte a exibição do sistema SVV_EXTERNAL_SCHEMAS.

Sintaxe

A sintaxe a seguir descreve o comando CREATE EXTERNAL SCHEMA usado para fazer referência a dados usando um catálogo de dados externo. Para obter mais informações, consulte Consultar dados externos usando o Amazon Redshift Spectrum.

CREATE EXTERNAL SCHEMA [IF NOT EXISTS] local_schema_name
FROM { [ DATA CATALOG ] | HIVE METASTORE | POSTGRES | MYSQL | KINESIS | MSK | REDSHIFT }
[ DATABASE 'database_name' ]
[ SCHEMA 'schema_name' ]
[ REGION 'aws-region' ]
[ URI 'hive_metastore_uri' [ PORT port_number ] ]
IAM_ROLE { default | 'SESSION' | 'arn:aws:iam::<Conta da AWS-id>:role/<role-name>' }
[ SECRET_ARN 'ssm-secret-arn' ]
[ AUTHENTICATION { none | iam } ]
[ CLUSTER_ARN 'arn:aws:kafka:<region>:<Conta da AWS-id>:cluster/msk/<cluster uuid>' ]
[ CATALOG_ROLE { 'SESSION' | 'catalog-role-arn-string' } ]
[ CREATE EXTERNAL DATABASE IF NOT EXISTS ]
[ CATALOG_ID 'Amazon Web Services account ID containing Glue or Lake Formation database' ]

A sintaxe a seguir descreve o comando CREATE EXTERNAL SCHEMA usado para fazer referência a dados usando uma consulta federada ao RDS POSTGRES ou Aurora PostgreSQL. Você também pode criar um esquema externo que faça referência a fontes de transmissão, como o Kinesis Data Streams. Para obter mais informações, consulte Consultar dados com consultas federadas no Amazon Redshift.

CREATE EXTERNAL SCHEMA [IF NOT EXISTS] local_schema_name
FROM POSTGRES
DATABASE 'federated_database_name' [SCHEMA 'schema_name']
URI 'hostname' [ PORT port_number ]
IAM_ROLE { default | 'arn:aws:iam::<Conta da AWS-id>:role/<role-name>' }
SECRET_ARN 'ssm-secret-arn'

A sintaxe a seguir descreve o comando CREATE EXTERNAL SCHEMA usado para fazer referência a dados usando uma consulta federada ao RDS MySQL ou Aurora MySQL. Para obter mais informações, consulte Consultar dados com consultas federadas no Amazon Redshift.

CREATE EXTERNAL SCHEMA [IF NOT EXISTS] local_schema_name
FROM MYSQL
DATABASE 'federated_database_name'
URI 'hostname' [ PORT port_number ]
IAM_ROLE { default | 'arn:aws:iam::<Conta da AWS-id>:role/<role-name>' }
SECRET_ARN 'ssm-secret-arn'

A sintaxe a seguir descreve o comando CREATE EXTERNAL SCHEMA usado para fazer referência a dados em uma transmissão do Kinesis. Para obter mais informações, consulte Ingestão de streaming para uma visão materializada.

CREATE EXTERNAL SCHEMA [IF NOT EXISTS] schema_name
FROM KINESIS
IAM_ROLE { default | 'arn:aws:iam::<Conta da AWS-id>:role/<role-name>' }

A sintaxe a seguir descreve o comando CREATE EXTERNAL SCHEMA usado para fazer referência ao cluster do Amazon Managed Streaming for Apache Kafka e seus tópicos dos quais ingerir. CLUSTER_ARN especifica o cluster do Amazon MSK do qual você está lendo dados. Para obter mais informações, consulte Ingestão de streaming para uma visão materializada.

CREATE EXTERNAL SCHEMA [IF NOT EXISTS] schema_name
FROM MSK
IAM_ROLE { default | 'arn:aws:iam::<Conta da AWS-id>:role/<role-name>' }
AUTHENTICATION { none | iam }
CLUSTER_ARN 'msk-cluster-arn';

A sintaxe a seguir descreve o comando CREATE EXTERNAL SCHEMA usado para fazer referência a dados usando uma consulta entre bancos de dados.

CREATE EXTERNAL SCHEMA local_schema_name
FROM  REDSHIFT
DATABASE 'redshift_database_name' SCHEMA 'redshift_schema_name'

Parâmetros

IF NOT EXISTS

Cláusula que indica que, se o esquema especificado existe, o comando não deve fazer alterações e retorna uma mensagem informando que o esquema existe, em vez de encerrar com um erro. Esta cláusula é útil para realizar desenvolvimento de scripts para que o script não falhe se o comando CREATE EXTERNAL SCHEMA tentar criar um esquema que já existe.

local_schema_name

Nome do novo esquema externo. Para obter mais informações sobre nomes válidos, consulte Nomes e identificadores.

FROM [ DATA CATALOG ] | HIVE METASTORE | POSTGRES | MYSQL | KINESIS | MSK | REDSHIFT

Uma palavra-chave que indica onde o banco de dados externo está localizado.

DATA CATALOG indica que o banco de dados externo está definido no catálogo de dados do Athena ou do AWS Glue Data Catalog.

Se o banco de dados externo estiver definido em um catálogo de dados em uma região da AWS diferente, o parâmetro REGION será obrigatório. DATA CATALOG é o valor padrão.

HIVE METASTORE indica que o banco de dados externo está definido em um metastore do Apache Hive. Se HIVE METASTORE estiver especificado, URI será obrigatório.

POSTGRES indica que o banco de dados externo está definido em RDS PostgreSQL ou Aurora PostgreSQL.

O MYSQL indica que o banco de dados externo está definido no RDS MySQL ou no Aurora MySQL.

O KINESIS indica que a fonte de dados é uma transmissão do Kinesis Data Streams.

O MSK indica que a fonte de dados é um tópico do Amazon MSK.

FROM REDSHIFT

Uma palavra-chave que indica que o banco de dados está localizado no Amazon Redshift.

DATABASE 'redshift_database_name' SCHEMA 'redshift_schema_name'

O nome do banco de dados do Amazon Redshift.

O redshift_schema_name indica o esquema no Amazon Redshift. O valor redshift_schema_name é public.

DATABASE 'federated_database_name'

Uma palavra-chave que indica o nome do banco de dados externo em um mecanismo de banco de dados PostgreSQL ou MySQL compatível.

[SCHEMA 'schema_name']

O schema_name indica o esquema em um mecanismo de banco de dados PostgreSQL compatível. O schema_name padrão é public.

Você não pode especificar um SCHEMA ao configurar uma consulta federada para um mecanismo de banco de dados MySQL compatível.

REGION 'aws-region'

Se o banco de dados externo for definido em um catálogo de dados do Athena ou do AWS Glue Data Catalog, a região da AWS na qual o banco de dados estará localizado. Esse parâmetro é necessário se o banco de dados for definido em um catálogo de dados .

URI 'hive_metastore_uri' [ PORT port_number ]

O URI de nome de host e port_number de um mecanismo de banco de dados PostgreSQL ou MySQL compatível. O hostname é o nó de cabeçalho do conjunto de réplicas. O endpoint deve ser acessível (roteável) pelo cluster do Amazon Redshift. O port_number padrão do PostgreSQL é 5432. O port_number padrão do MySQL é 3306.

Se o banco de dados estiver em um metastore do Hive, especifique o URI e, como opção, o número da porta do metastore. O número da porta padrão é 9083.

Um URI não contém uma especificação de protocolo (“http://”). Um exemplo de URI válido: uri '172.10.10.10'.

nota

O mecanismo de banco de dados PostgreSQL ou MySQL compatível deve estar na mesma VPC do cluster do Amazon Redshift. Crie um grupo de segurança vinculando o Amazon Redshift e o RDS PostgreSQL ou o Aurora PostgreSQL.

IAM_ROLE { default | 'SESSION' | 'arn:aws:iam::<Conta da AWS-id>:role/<role-name>' }

Use a palavra-chave padrão para que o Amazon Redshift use a função do IAM definida como padrão e associada ao cluster quando o comando CREATE EXTERNAL SCHEMA for executado.

Use 'SESSION' se você se conectar ao cluster do Amazon Redshift usando uma identidade federada e acesse as tabelas do esquema externo criado usando esse comando. Para obter mais informações, consulte “Using a federated identity to manage Amazon Redshift access to local resources and Amazon Redshift Spectrum external tables” (Usar uma identidade federada para gerenciar o acesso do Amazon Redshift aos recursos locais e a tabelas externas do Amazon Redshift Spectrum), que explica como configurar uma identidade federada. Observe que essa configuração, que usa 'SESSION' no lugar do ARN, só poderá ser usada se o esquema for criado usando DATA CATALOG.

Use o nome do recurso da Amazon (ARN) de uma função do IAM que seu cluster usa para autenticação e autorização. No mínimo, a função do IAM deve ter permissão para executar uma operação LIST no bucket do Amazon S3 a ser acessado e uma operação GET nos objetos do Amazon S3 que constam no bucket.

O exemplo a seguir mostra a sintaxe da string do parâmetro IAM_ROLE para um único ARN.

IAM_ROLE 'arn:aws:iam::<aws-account-id>:role/<role-name>'

Você pode encadear funções para que seu cluster possa assumir outra função do IAM, possivelmente pertencente a outra conta. Você pode encadear até 10 funções. Para ver um exemplo de perfis de encadeamento, consulte Encadeamento de funções do IAM no Amazon Redshift Spectrum.

Anexe a essa função do IAM uma política de permissões do IAM semelhante à política descrita a seguir.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AccessSecret",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetResourcePolicy",
                "secretsmanager:GetSecretValue",
                "secretsmanager:DescribeSecret",
                "secretsmanager:ListSecretVersionIds"
            ],
            "Resource": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-rds-secret-VNenFy"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetRandomPassword",
                "secretsmanager:ListSecrets"
            ],
            "Resource": "*"
        }
    ]
}

Para obter as etapas para criar uma função do IAM a ser usada com consulta federada, consulte Criar um segredo e uma função do IAM para usar consultas federadas.

nota

Não inclua espaços na lista de funções encadeadas.

O seguinte mostra a sintaxe do encadeamento de três funções.

IAM_ROLE 'arn:aws:iam::<aws-account-id>:role/<role-1-name>,arn:aws:iam::<aws-account-id>:role/<role-2-name>,arn:aws:iam::<aws-account-id>:role/<role-3-name>'
SECRET_ARN 'ssm-secret-arn'

O nome do recurso da Amazon (ARN) de um segredo de mecanismo de banco de dados PostgreSQL ou MySQL compatível criado usando o AWS Secrets Manager. Para obter informações sobre como criar e recuperar um ARN para um segredo, consulte Criar um segredo básico e Recuperar o segredo do valor do segredo no AWS Secrets ManagerManual do usuário.

CATALOG_ROLE { 'SESSION' | catalog-role-arn-string}

Use 'SESSION' para se conectar ao cluster do Amazon Redshift usando uma identidade federada para autenticação e autorização para o catálogo de dados. Para obter mais informações sobre como concluir as etapas da identidade federada, consulte “Using a federated identity to manage Amazon Redshift access to local resources and Amazon Redshift Spectrum external tables” (Usar uma identidade federada para gerenciar o acesso do Amazon Redshift aos recursos locais e a tabelas externas do Amazon Redshift Spectrum). Observe que o perfil 'SESSION' só poderá ser usado se o esquema for criado no CATÁLOGO DE DADOS.

Use o nome do recurso da Amazon (ARN) de um perfil do IAM que o cluster usa para autenticação e autorização do catálogo de dados.

Se CATALOG_ROLE não for especificado, o Amazon Redshift usará a IAM_ROLE especificada. A função do catálogo deve ter permissão para acessar o catálogo de dados no AWS Glue ou Athena. Para obter mais informações, consulte Políticas do IAM do Amazon Redshift Spectrum.

O exemplo a seguir mostra a sintaxe da string do parâmetro CATALOG_ROLE para um único ARN.

CATALOG_ROLE 'arn:aws:iam::<aws-account-id>:role/<catalog-role>'

Você pode encadear funções para que seu cluster possa assumir outra função do IAM, possivelmente pertencente a outra conta. Você pode encadear até 10 funções. Para obter mais informações, consulte Encadeamento de funções do IAM no Amazon Redshift Spectrum.

nota

A lista de funções encadeadas não deve incluir espaços.

O seguinte mostra a sintaxe do encadeamento de três funções.

CATALOG_ROLE 'arn:aws:iam::<aws-account-id>:role/<catalog-role-1-name>,arn:aws:iam::<aws-account-id>:role/<catalog-role-2-name>,arn:aws:iam::<aws-account-id>:role/<catalog-role-3-name>'

CREATE EXTERNAL DATABASE IF NOT EXISTS

Cláusula que cria um banco de dados externo com o nome especificado pelo argumento DATABASE, se o banco de dados externo especificado não existir. Se o banco de dados externo especificado existir, o comando não realizará alterações. Nesse caso, o comando retorna uma mensagem informando que o banco de dados externo existe, em vez de finalizar com um erro.

nota

CREATE EXTERNAL DATABASE IF NOT EXISTS não pode ser usado com o comando HIVE METASTORE.

Para usar CREATE EXTERNAL DATABASE IF NOT EXISTS com um catálogo de dados habilitado para AWS Lake Formation, você precisa da permissão CREATE_DATABASE no catálogo de dados.

CATALOG_ID “ID da conta da Amazon Web Services que contém o banco de dados do Glue ou do Lake Formation”

O ID da conta em que o banco de dados do catálogo de dados está armazenado.

CATALOG_ID só pode ser especificado se você planeja se conectar ao cluster do Amazon Redshift ou ao Amazon Redshift Serverless usando uma identidade federada para autenticação e autorização do catálogo de dados por meio da definição de uma das seguintes opções:

  • CATALOG_ROLE para 'SESSION'

  • IAM_ROLE como 'SESSION' e 'CATALOG_ROLE' definido como o padrão

Para obter mais informações sobre como concluir as etapas da identidade federada, consulte “Using a federated identity to manage Amazon Redshift access to local resources and Amazon Redshift Spectrum external tables” (Usar uma identidade federada para gerenciar o acesso do Amazon Redshift aos recursos locais e a tabelas externas do Amazon Redshift Spectrum).

AUTHENTICATION

O tipo de autenticação definido para ingestão de streaming. A ingestão de streaming com tipos de autenticação funciona com o Managed Streaming for Apache Kafka. Os tipos de AUTHENTICATION são os seguintes:

CLUSTER_ARN

Para ingestão de streaming, o identificador do cluster do Amazon Managed Streaming for Apache Kafka do qual você está transmitindo. Para obter mais informações, consulte Ingestão de streaming.

Observações de uso

Para limites ao usar o catálogo de dados do Athena, consulte Limites do Athena na Referência geral da AWS.

Para os limites ao usar o AWS Glue Data Catalog, consulte Limites do AWS Glue no Referência geral da AWS.

Esses limites não se aplicam a um metastore do Hive.

O máximo de esquemas permitido por banco de dados é 9,9 mil. Para obter mais informações, consulte Cotas e limites no Guia de gerenciamento do Amazon Redshift.

Para cancelar o registro do esquema, use o comando DROP SCHEMA.

Para visualizar detalhes dos esquemas externos, consulte estas visualizações do sistema:

Exemplos

O exemplo a seguir cria um esquema externo usando um banco de dados em um catálogo de dados denominado sampledb na região Oeste dos EUA (Oregon). Use esse exemplo com um catálogo de dados do Athena ou AWS Glue.

create external schema spectrum_schema
from data catalog
database 'sampledb'
region 'us-west-2'
iam_role 'arn:aws:iam::123456789012:role/MySpectrumRole';

O exemplo a seguir cria um esquema externo e um novo banco de dados externo denominado spectrum_db.

create external schema spectrum_schema
from data catalog
database 'spectrum_db'
iam_role 'arn:aws:iam::123456789012:role/MySpectrumRole'
create external database if not exists;

O exemplo a seguir cria um esquema externo usando um banco de dados do metastore do Hive denominado hive_db.

create external schema hive_schema
from hive metastore
database 'hive_db'
uri '172.10.10.10' port 99
iam_role 'arn:aws:iam::123456789012:role/MySpectrumRole';

O exemplo a seguir encadeia funções para usar a função myS3Role para acessar o Amazon S3 e usa myAthenaRole para acesso ao catálogo de dados. Para obter mais informações, consulte Encadeamento de funções do IAM no Amazon Redshift Spectrum.

create external schema spectrum_schema
from data catalog
database 'spectrum_db'
iam_role 'arn:aws:iam::123456789012:role/myRedshiftRole,arn:aws:iam::123456789012:role/myS3Role'
catalog_role 'arn:aws:iam::123456789012:role/myAthenaRole'
create external database if not exists;

O exemplo a seguir cria um esquema externo que faz referência a um banco de dados do Aurora PostgreSQL. 

CREATE EXTERNAL SCHEMA [IF NOT EXISTS] myRedshiftSchema
FROM POSTGRES
DATABASE 'my_aurora_db' SCHEMA 'my_aurora_schema'
URI 'endpoint to aurora hostname' PORT 5432  
IAM_ROLE 'arn:aws:iam::123456789012:role/MyAuroraRole'
SECRET_ARN 'arn:aws:secretsmanager:us-east-2:123456789012:secret:development/MyTestDatabase-AbCdEf'

O exemplo a seguir cria um esquema externo para referenciar o sales_db importado no cluster de consumidor.

CREATE EXTERNAL SCHEMA sales_schema FROM REDSHIFT DATABASE 'sales_db' SCHEMA 'public';

O exemplo a seguir cria um esquema externo que faz referência a um banco de dados do Aurora MySQL. 

CREATE EXTERNAL SCHEMA [IF NOT EXISTS] myRedshiftSchema
FROM MYSQL
DATABASE 'my_aurora_db'
URI 'endpoint to aurora hostname'
IAM_ROLE 'arn:aws:iam::123456789012:role/MyAuroraRole'
SECRET_ARN 'arn:aws:secretsmanager:us-east-2:123456789012:secret:development/MyTestDatabase-AbCdEf'