Connettore Amazon Athena per Azure Synapse - Amazon Athena
PrerequisitiLimitazioniTerminiParametriSupporto dei tipi di datiPartizioni e suddivisioniPrestazioniInterrogazioni passthroughInformazioni sulla licenzaRisorse aggiuntive

Connettore Amazon Athena per Azure Synapse

Il connettore Amazon Athena per Azure Synapse Analytics consente ad Amazon Athena di eseguire query SQL sui database Azure Synapse utilizzando JDBC.

Questo connettore può essere registrato con Glue Data Catalog come catalogo federato. Supporta i controlli di accesso ai dati definiti in Lake Formation a livello di catalogo, database, tabella, colonna, riga e tag. Questo connettore utilizza Glue Connections per centralizzare le proprietà di configurazione in Glue.

Prerequisiti

Limitazioni

  • Le operazioni di scrittura DDL non sono supportate.

  • In una configurazione multiplex, il bucket di spill e il prefisso sono condivisi tra tutte le istanze del database.

  • Eventuali limiti Lambda pertinenti. Per ulteriori informazioni, consulta la sezione Quote Lambda nella Guida per gli sviluppatori di AWS Lambda.

  • Nelle condizioni di filtro, è necessario impostare i tipi di dati Date e Timestamp sul tipo di dati appropriato.

  • Per cercare valori negativi del tipo Real e Float, utilizza l'operatore <= o >=.

  • I tipi di dati binary, varbinary, image e rowversion non sono supportati.

Termini

I seguenti termini si riferiscono al connettore Synapse.

  • Istanza del database: qualsiasi istanza del database distribuita on-premise, su Amazon EC2 o su Amazon RDS.

  • Gestore: un gestore Lambda che accede all'istanza del database. Un gestore può gestire i metadati o i record di dati.

  • Gestore dei metadati: un gestore Lambda che recupera i metadati dall'istanza del database.

  • Gestore dei record: un gestore Lambda che recupera i record di dati dall'istanza del database.

  • Gestore composito: un gestore Lambda che recupera sia i metadati sia i record di dati dall'istanza del database.

  • Proprietà o parametro: una proprietà del database utilizzata dai gestori per estrarre le informazioni del database. Queste proprietà vengono configurate come variabili di ambiente Lambda.

  • Stringa di connessione: una stringa di testo utilizzata per stabilire una connessione a un'istanza del database.

  • Catalogo: un catalogo non di AWS Glue registrato in Athena che costituisce un prefisso obbligatorio per la proprietà connection_string.

  • Gestore multiplex: un gestore Lambda in grado di accettare e utilizzare più connessioni al database.

Parametri

Utilizza i parametri illustrati in questa sezione per configurare il connettore Synapse.

Nota

I connettori di origine dati Athena creati il 3 dicembre 2024 e versioni successive utilizzano connessioni. AWS Glue

I nomi e le definizioni dei parametri elencati di seguito si riferiscono ai connettori di origine dati Athena creati prima del 3 dicembre 2024. Questi possono differire dalle proprietà di AWS Glueconnessione corrispondenti. A partire dal 3 dicembre 2024, utilizza i parametri seguenti solo quando distribuisci manualmente una versione precedente di un connettore di origine dati Athena.

Si consiglia di configurare un connettore Synapse utilizzando un oggetto Glue connections. Per fare ciò, imposta la variabile di glue_connection ambiente del connettore Synapse Lambda sul nome della connessione Glue da utilizzare.

Proprietà delle connessioni Glue

Utilizzare il seguente comando per ottenere lo schema per una connessione Glue. Questo schema contiene tutti i parametri che puoi usare per controllare la tua connessione.

aws glue describe-connection-type --connection-type SYNAPSE

Proprietà dell'ambiente

  • glue_connection — Specificate il nome della connessione Glue associata al connettore federato.

  • casing_mode — (Facoltativo) Specifica come gestire il casing per i nomi di schemi e tabelle. Il parametro casing_mode utilizza i seguenti valori per specificare il comportamento di formattazione di maiuscole e minuscole e della mappatura delle colonne:

    • none — Non modifica le maiuscole e minuscole dello schema e dei nomi delle tabelle specificati. Questa è l'impostazione predefinita per i connettori a cui è associata una connessione di collegamento.

    • upper — Tutti i nomi di schemi e tabelle specificati in maiuscolo.

    • minuscolo: tutti i nomi di schemi e tabelle specificati in minuscolo.

Nota

  • Tutti i connettori che utilizzano le connessioni Glue devono essere utilizzati Gestione dei segreti AWS per memorizzare le credenziali.

  • Il connettore Synapse creato utilizzando le connessioni Glue non supporta l'uso di un gestore di multiplexing.

  • Il connettore Synapse creato utilizzando le connessioni Glue supporta ConnectionSchemaVersion solo 2.

Stringa di connessione

Utilizza una stringa di connessione JDBC nel formato seguente per connetterti a un'istanza del database.

synapse://${jdbc_connection_string}

Utilizzo di un gestore multiplex

Puoi utilizzare un gestore multiplex per connetterti a più istanze del database con una singola funzione Lambda. Le richieste vengono indirizzate in base al nome del catalogo. Utilizza le seguenti classi in Lambda.

Gestore Classe
Gestore composito SynapseMuxCompositeHandler
Gestore dei metadati SynapseMuxMetadataHandler
Gestore dei record SynapseMuxRecordHandler
Parametri del gestore multiplex
Parametro Descrizione
$catalog_connection_string Obbligatorio. Una stringa di connessione di un'istanza del database. Appone alla variabile di ambiente un prefisso con il nome del catalogo utilizzato in Athena. Ad esempio, se il catalogo registrato presso Athena è mysynapsecatalog, il nome della variabile di ambiente è mysynapsecatalog_connection_string.
default Obbligatorio. La stringa di connessione predefinita. Questa stringa viene utilizzata quando il catalogo è lambda:${AWS_LAMBDA_FUNCTION_NAME}.

Le seguenti proprietà di esempio si riferiscono a una funzione Lambda Synapse MUX che supporta due istanze del database: synapse1 (il valore predefinito) e synapse2.

Proprietà Valore
default synapse://jdbc:synapse://synapse1.hostname:port;databaseName=<database_name>;${secret1_name}
synapse_catalog1_connection_string synapse://jdbc:synapse://synapse1.hostname:port;databaseName=<database_name>;${secret1_name}
synapse_catalog2_connection_string synapse://jdbc:synapse://synapse2.hostname:port;databaseName=<database_name>;${secret2_name}
Specifica delle credenziali

Per fornire un nome utente e una password per il database nella stringa di connessione JDBC, puoi utilizzare le proprietà della stringa di connessione o Gestione dei segreti AWS.

  • Stringa di connessione: puoi specificare un nome utente e una password come proprietà nella stringa di connessione JDBC.

    Importante

    Come best practice di sicurezza, non utilizzare credenziali codificate nelle variabili di ambiente o nelle stringhe di connessione. Per informazioni su come trasferire i segreti codificati in Gestione dei segreti AWS, consulta Trasferimento dei segreti codificati in Gestione dei segreti AWS nella Guida per l'utente di Gestione dei segreti AWS.

  • Gestione dei segreti AWS: per utilizzare la funzione Athena Federated Query con Gestione dei segreti AWS, il VPC collegato alla funzione Lambda deve disporre dell'accesso a Internet o di un endpoint VPC per connettersi a Secrets Manager.

    Puoi inserire il nome di un segreto in Gestione dei segreti AWS nella stringa di connessione JDBC. Il connettore sostituisce il nome del segreto con i valori username e password di Secrets Manager.

    Per le istanze del database Amazon RDS, questo supporto è strettamente integrato. Se utilizzi Amazon RDS, ti consigliamo vivamente di utilizzare Gestione dei segreti AWS e la rotazione delle credenziali. Se il tuo database non utilizza Amazon RDS, archivia le credenziali come JSON nel seguente formato:

    {"username": "${username}", "password": "${password}"}
Esempio di stringa di connessione con nome del segreto

La stringa seguente ha il nome del segreto ${secret_name}.

synapse://jdbc:synapse://hostname:port;databaseName=<database_name>;${secret_name}

Il connettore utilizza il nome del segreto per recuperare i segreti e fornire il nome utente e la password, come nell'esempio seguente.

synapse://jdbc:synapse://hostname:port;databaseName=<database_name>;user=<user>;password=<password>

Utilizzo di un gestore a singola connessione

Puoi utilizzare i seguenti gestori di metadati e record a singola connessione per connetterti a una singola istanza Synapse.

Tipo di gestore Classe
Gestore composito SynapseCompositeHandler
Gestore dei metadati SynapseMetadataHandler
Gestore dei record SynapseRecordHandler
Parametri del gestore a singola connessione
Parametro Descrizione
default Obbligatorio. La stringa di connessione predefinita.

I gestori a singola connessione supportano una sola istanza del database e devono fornire un parametro di stringa di connessione del tipo default. Tutte le altre stringhe di connessione vengono ignorate.

La seguente proprietà di esempio si riferisce a una singola istanza Synapse supportata da una funzione Lambda.

Proprietà Valore
default synapse://jdbc:sqlserver://hostname:port;databaseName=<database_name>;${secret_name}

Configurazione dell'autenticazione Active Directory

Il connettore Azure Synapse di Amazon Athena supporta l'autenticazione Microsoft Active Directory. Prima di iniziare, è necessario configurare un utente amministrativo nel portale di Microsoft Azure e quindi utilizzare Gestione dei segreti AWS per creare un segreto.

Impostazione dell'utente amministrativo di Active Directory

  1. Utilizzando un account con privilegi amministrativi, accedi al portale Microsoft Azure all'indirizzo https://portal.azure.com/.

  2. Nella casella di ricerca, inserisci Azure Synapse Analytics quindi seleziona Azure Synapse Analytics.

    Seleziona Azure Synapse Analytics.

  3. Apri il menu a sinistra.

    Seleziona il menu del portale Azure.

  4. Nel riquadro di navigazione, seleziona Azure Active Directory.

  5. Nella scheda Imposta admin, imposta Adim di Active Directory su un utente nuovo o esistente.

    Utilizza la scheda Imposta admin

  6. In Gestione dei segreti AWS, memorizza il nome utente admin e le credenziali password. Per informazioni sulla creazione di un segreto in Secrets Manager, consulta la pagina Crea un segreto Gestione dei segreti AWS.

Visualizzazione del segreto in Gestione dei segreti

  1. Apri la console di Secrets Manager all'indirizzo https://console.aws.amazon.com/secretsmanager/.

  2. Nel riquadro di navigazione, scegli Secrets (Segreti).

  3. Nella pagina Secrets (Segreti), scegli il collegamento al tuo segreto.

  4. Nella pagina dei dettagli del segreto, scegli Retrieve secret value (Recupera il valore di un segreto).

    Visualizzazione dei segreti in Gestione dei segreti AWS.
Modifica della stringa di connessione

Per abilitare l'autenticazione Active Directory del connettore, modifica la stringa di connessione utilizzando la seguente sintassi:

synapse://jdbc:synapse://hostname:port;databaseName=database_name;authentication=ActiveDirectoryPassword;{secret_name}
Utilizzo di ActiveDirectoryServicePrincipal

Il connettore Azure Synapse di Amazon Athena supporta anche ActiveDirectoryServicePrincipal. Per l'abilitazione, modifica la stringa di connessione come segue.

synapse://jdbc:synapse://hostname:port;databaseName=database_name;authentication=ActiveDirectoryServicePrincipal;{secret_name}

Per secret_name, specificare l'ID dell'applicazione o del client come nome utente e il segreto di un'identità principale di servizio nella password.

Parametri di spill

L'SDK Lambda può riversare i dati su Amazon S3. Tutte le istanze del database a cui accede la stessa funzione Lambda riversano i dati nella stessa posizione.

Parametro Descrizione
spill_bucket Obbligatorio. Nome del bucket di spill.
spill_prefix Obbligatorio. Prefisso della chiave del bucket di spill.
spill_put_request_headers (Facoltativo) Una mappa codificata in JSON delle intestazioni e dei valori della richiesta per la richiesta putObject di Amazon S3 utilizzata per lo spill (ad esempio, {"x-amz-server-side-encryption" : "AES256"}). Per altre possibili intestazioni, consulta l'argomento relativo a PutObject nella Documentazione di riferimento dell'API di Amazon Simple Storage Service.

Supporto dei tipi di dati

Nella tabella seguente vengono illustrati i tipi di dati corrispondenti per Synapse e Apache Arrow.

Synapse Arrow
bit TINYINT
tinyint SMALLINT
smallint SMALLINT
int INT
bigint BIGINT
decimal DECIMAL
numeric FLOAT8
smallmoney FLOAT8
money DECIMAL
float[24] FLOAT4
float[53] FLOAT8
real FLOAT4
datetime Date(MILLISECOND)
datetime2 Date(MILLISECOND)
smalldatetime Date(MILLISECOND)
date Date(DAY)
time VARCHAR
datetimeoffset Date(MILLISECOND)
char[n] VARCHAR
varchar[n/max] VARCHAR
nchar[n] VARCHAR
nvarchar[n/max] VARCHAR

Partizioni e suddivisioni

Una partizione è rappresentata da una singola colonna di partizione di tipo varchar. Synapse supporta il partizionamento a intervalli, quindi il partizionamento viene implementato estraendo la colonna della partizione e l'intervallo della stessa dalle tabelle dei metadati di Synapse. Questi valori di intervallo vengono utilizzati per creare le suddivisioni.

Prestazioni

La selezione di un sottoinsieme di colonne rallenta notevolmente l'esecuzione delle query. Il connettore presenta una significativa limitazione della larghezza di banda della rete dovuta alla simultaneità.

Il connettore Athena Synapse esegue il pushdown del predicato per ridurre la quantità di dati scansionati dalla query. I predicati semplici e le espressioni complesse vengono inviati al connettore per ridurre la quantità di dati scansionati e ridurre il tempo di esecuzione delle query.

Predicati

Un predicato è un'espressione nella clausola WHERE di una query SQL che valuta a un valore booleano e filtra le righe in base a più condizioni. Il connettore Synapse di Athena può combinare queste espressioni e inviarle direttamente a Synapse per migliorare le funzionalità e per ridurre la quantità di dati scansionati.

I seguenti operatori del connettore Synapse di Athena supportano il pushdown dei predicati:

  • Booleano: AND, OR, NOT

  • Uguaglianza: EQUAL, NOT_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, NULL_IF, IS_NULL

  • Aritmetica: ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULUS, NEGATE

  • Altro: LIKE_PATTERN, IN

Esempio di pushdown combinato

Per le funzionalità di esecuzione di query avanzate, combina i tipi di pushdown, come nell'esempio seguente:

SELECT * 
FROM my_table 
WHERE col_a > 10 
    AND ((col_a + col_b) > (col_c % col_d)) 
    AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%');

Interrogazioni passthrough

Il connettore Synapse supporta le query passthrough. Le query passthrough utilizzano una funzione di tabella per inviare l'intera query alla fonte di dati per l'esecuzione.

Per utilizzare le query passthrough con Synapse, si può utilizzare la seguente sintassi:

SELECT * FROM TABLE(
        system.query(
            query => 'query string'
        ))

La seguente query di esempio invia una query a una fonte di dati in Synapse. La query seleziona tutte le colonne della customer tabella, limitando i risultati a 10.

SELECT * FROM TABLE(
        system.query(
            query => 'SELECT * FROM customer LIMIT 10'
        ))

Informazioni sulla licenza

Utilizzando questo connettore, riconosci l'inclusione di componenti di terze parti, un elenco dei quali è disponibile nel file pom.xml di questo connettore, e accetti i termini delle rispettive licenze di terze parti fornite nel file LICENSE.txt su GitHub.com.

Risorse aggiuntive