Connettore Amazon Athena OpenSearch - Amazon Athena
PrerequisitiTerminiParametriConfigurazione di database e tabelle in AWS GlueEsecuzione di query SQLPrestazioniInterrogazioni pass-throughRisorse aggiuntive

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Connettore Amazon Athena OpenSearch

OpenSearch Servizio

Il OpenSearch connettore Amazon Athena consente ad Amazon Athena di comunicare con le OpenSearch tue istanze in modo da poter utilizzare SQL per interrogare i tuoi dati. OpenSearch

Nota

A causa di un problema noto, il OpenSearch connettore non può essere utilizzato con un VPC.

Se hai abilitato Lake Formation nel tuo account, il ruolo IAM per il tuo connettore Lambda federato Athena che hai distribuito nell'accesso in lettura deve avere accesso in lettura in AWS Serverless Application Repository Lake Formation a. AWS Glue Data Catalog

Prerequisiti

Termini

I seguenti termini si riferiscono al connettore. OpenSearch

  • Dominio: un nome che questo connettore associa all'endpoint dell'istanza. OpenSearch Il dominio viene utilizzato anche come nome del database. Per OpenSearch le istanze definite all'interno del OpenSearch servizio Amazon, il dominio è individuabile automaticamente. Per altre istanze, devi fornire una mappatura tra il nome di dominio e l'endpoint.

  • Indice: una tabella di database definita nell'istanza. OpenSearch

  • Mappatura: se un indice è una tabella del database, la mappatura è il relativo schema (ossia le definizioni dei campi e degli attributi).

    Questo connettore supporta sia il recupero dei metadati dall' OpenSearch istanza che da. AWS Glue Data Catalog Se il connettore trova un AWS Glue database e una tabella che corrispondono ai nomi di OpenSearch dominio e di indice, tenta di utilizzarli per la definizione dello schema. Ti consigliamo di creare la AWS Glue tabella in modo che sia un superset di tutti i campi dell' OpenSearch indice.

  • Documento: un record all'interno di una tabella del database.

  • Flusso di dati: dati basati su tempo composti da più indici di supporto. Per ulteriori informazioni, consulta Data stream nella OpenSearch documentazione e Introduzione ai flussi di dati nella Amazon OpenSearch Service Developer Guide.

    Nota

    Poiché gli indici dei flussi di dati sono creati e gestiti internamente da open search, il connettore sceglie dal primo indice disponibile la mappatura dello schema. Per questo motivo, consigliamo vivamente di configurare una AWS Glue tabella come fonte di metadati supplementare. Per ulteriori informazioni, consulta Configurazione di database e tabelle in AWS Glue.

Parametri

Usa le variabili di ambiente Lambda in questa sezione per configurare il OpenSearch connettore.

  • spill_bucket: specifica il bucket Amazon S3 per i dati che superano i limiti della funzione Lambda.

  • spill_prefix: (facoltativo) per impostazione predefinita, viene utilizzata una sottocartella nello spill_bucket specificato chiamata athena-federation-spill. Ti consigliamo di configurare un ciclo di vita dell'archiviazione di Amazon S3 in questa posizione per eliminare gli spill più vecchi di un numero predeterminato di giorni o ore.

  • 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 il riferimento PutObjectall'API di Amazon Simple Storage Service.

  • kms_key_id: (facoltativo) per impostazione predefinita, tutti i dati riversati in Amazon S3 vengono crittografati utilizzando la modalità di crittografia autenticata AES-GCM e una chiave generata casualmente. Per fare in modo che la tua funzione Lambda utilizzi chiavi di crittografia più potenti generate da KMS come a7e63k4b-8loc-40db-a2a1-4d0en2cd8331, puoi specificare l'ID della chiave KMS.

  • disable_spill_encryption: (facoltativo) se impostato su True, disabilita la crittografia dello spill. L'impostazione predefinita è False: in questo modo, i dati riversati su S3 vengono crittografati utilizzando AES-GCM tramite una chiave generata casualmente o una chiave generata mediante KMS. La disabilitazione della crittografia dello spill può migliorare le prestazioni, soprattutto se la posizione dello spill utilizza la crittografia lato server.

  • disable_glue — (Facoltativo) Se presente e impostato su true, il connettore non tenta di recuperare metadati supplementari da. AWS Glue

  • query_timeout_cluster: il periodo di timeout, in secondi, per le query sullo stato del cluster utilizzate nella generazione di scansioni in parallelo.

  • query_timeout_search: il periodo di timeout, in secondi, per le query di ricerca utilizzate per il recupero di documenti da un indice.

  • auto_discover_endpoint: un valore booleano. Il valore predefinito è true. Quando utilizzi il OpenSearch servizio Amazon e imposti questo parametro su true, il connettore può scoprire automaticamente i tuoi domini ed endpoint chiamando le operazioni API appropriate per descrivere o elencare sul Servizio. OpenSearch Per qualsiasi altro tipo di OpenSearch istanza (ad esempio, self-hosted), devi specificare gli endpoint di dominio associati nella variabile. domain_mapping Seauto_discover_endpoint=true, il connettore utilizza AWS le credenziali per l'autenticazione al Servizio. OpenSearch In caso contrario, il connettore recupera le credenziali del nome utente e della password tramite la variabile. AWS Secrets Manager domain_mapping

  • domain_mapping: viene utilizzato solo quando auto_discover_endpoint è impostato su false e definisce la mappatura tra i nomi di dominio e gli endpoint associati. La domain_mapping variabile può contenere più OpenSearch endpoint nel seguente formato:

    domain1=endpoint1,domain2=endpoint2,domain3=endpoint3,...

    Ai fini dell'autenticazione su un OpenSearch endpoint, il connettore supporta stringhe sostitutive inserite utilizzando il formato ${SecretName}: con nome utente e password recuperati da. AWS Secrets Manager I due punti (:) alla fine dell'espressione fungono da separatore dal resto dell'endpoint.

    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 hardcoded in, consultate Move hardcoded secret in nella Guida per l' AWS Secrets Manager utente. AWS Secrets ManagerAWS Secrets Manager

    Nell'esempio seguente viene utilizzato il segreto opensearch-creds.

    movies=https://${opensearch-creds}:search-movies-ne...qu.us-east-1.es.amazonaws.com

    In fase di runtime, ${opensearch-creds} viene visualizzato come nome utente e password, come nell'esempio seguente.

    movies=https://myusername@mypassword:search-movies-ne...qu.us-east-1.es.amazonaws.com

    Nel parametro domain_mapping, ogni coppia dominio-endpoint può utilizzare un segreto diverso. Il segreto stesso deve essere specificato nel formato nome_utente@password. Sebbene la password possa contenere segni @, il primo @ funge da separatore da user_name (nome utente).

    È anche importante tenere a mente che questo connettore utilizza la virgola (,) e il segno uguale (=) come separatori per le coppie dominio-endpoint. Per questo motivo, non è consigliabile utilizzarli da nessuna parte all'interno del secreto archiviato.

Configurazione di database e tabelle in AWS Glue

Il connettore ottiene le informazioni sui metadati utilizzando AWS Glue o. OpenSearch È possibile impostare una AWS Glue tabella come fonte di definizione dei metadati supplementare. Per abilitare questa funzionalità, definisci un AWS Glue database e una tabella che corrispondano al dominio e all'indice della fonte che stai integrando. Il connettore può inoltre sfruttare le definizioni dei metadati memorizzate nell' OpenSearch istanza recuperando la mappatura per l'indice specificato.

Definizione dei metadati per gli array in OpenSearch

OpenSearch non dispone di un tipo di dati di array dedicato. Qualsiasi campo può contenere zero o più valori purché siano dello stesso tipo di dati. Se si desidera utilizzare OpenSearch come fonte di definizione dei metadati, è necessario definire una _meta proprietà per tutti gli indici utilizzati con Athena per i campi che devono essere considerati un elenco o un array. Se non completi questo passaggio, le query restituiscono solo il primo elemento nel campo elenco. Quando specifichi la proprietà _meta, i nomi dei campi devono essere completamente qualificati per le strutture JSON nidificate (ad esempio, address.street, dove street è un campo nidificato all'interno di una struttura address).

L'esempio seguente definisce gli elenchi actor e genre nella tabella movies.

PUT movies/_mapping 
{ 
  "_meta": { 
    "actor": "list", 
    "genre": "list" 
  } 
}

Tipi di dati

Il OpenSearch connettore può estrarre le definizioni dei metadati da entrambe le istanze o dall'istanza AWS Glue . OpenSearch Il connettore utilizza la mappatura illustrata nella seguente tabella per convertire le definizioni in tipi di dati Apache Arrow, inclusi i punti indicati nella sezione seguente.

OpenSearch Apache Arrow AWS Glue
text, keyword, binary VARCHAR string
Long BIGINT bigint
scaled_float BIGINT SCALED_FLOAT(...)
integer INT int
short SMALLINT smallint
byte TINYINT tinyint
double FLOAT8 double
float, half_float FLOAT4 float
booleano BIT booleano
date, date_nanos DATEMILLI timestamp
Struttura JSON STRUCT STRUCT
_meta (per informazioni, consulta la sezione Definizione dei metadati per gli array in OpenSearch.) LIST ARRAY

Note sui tipi di dati

  • Attualmente, il connettore supporta solo OpenSearch i AWS Glue tipi di dati elencati nella tabella precedente.

  • Un scaled_float è un numero a virgola mobile scalato in base a un fattore di scala fisso doppio e rappresentato come BIGINT in Apache Arrow. Ad esempio, 0,756 con un fattore di scala pari a 100 viene arrotondato a 76.

  • Per definire un scaled_float in AWS Glue, è necessario selezionare il tipo di array colonna e dichiarare il campo utilizzando il formato SCALED_FLOAT (scaling_factor).

    Gli esempi seguenti sono validi:

    SCALED_FLOAT(10.51) 
SCALED_FLOAT(100) 
SCALED_FLOAT(100.0)

    Gli esempi seguenti non sono validi:

    SCALED_FLOAT(10.) 
SCALED_FLOAT(.5)

  • Durante la conversione da date_nanos a DATEMILLI, i nanosecondi vengono arrotondati al millisecondo più vicino. I valori validi per date e date_nanos includono, senza limitazione, i seguenti formati:

    "2020-05-18T10:15:30.123456789" 
"2020-05-15T06:50:01.123Z" 
"2020-05-15T06:49:30.123-05:00" 
1589525370001 (epoch milliseconds)

  • An OpenSearch binary è una rappresentazione in formato stringa di un valore binario codificato utilizzando e convertito in un. Base64 VARCHAR

Esecuzione di query SQL

Di seguito sono riportati alcuni esempi di query DDL che puoi utilizzare con questo connettore. Negli esempi, function_name corrisponde al nome della funzione Lambda, domain è il nome del dominio su cui desideri eseguire una query e index è il nome del tuo indice.

SHOW DATABASES in `lambda:function_name`
SHOW TABLES in `lambda:function_name`.domain
DESCRIBE `lambda:function_name`.domain.index

Prestazioni

Il OpenSearch connettore Athena supporta scansioni parallele basate su shard. Il connettore utilizza le informazioni sullo stato del cluster recuperate dall' OpenSearch istanza per generare più richieste per una query di ricerca di documenti. Le richieste vengono suddivise per ogni partizione ed eseguite in simultanea.

Il connettore inoltre esegue il pushdown dei predicati come parte delle sue query di ricerca di documenti. I seguenti query e predicato di esempio mostrano come il connettore utilizza il pushdown del predicato.

Query

SELECT * FROM "lambda:elasticsearch".movies.movies 
WHERE year >= 1955 AND year <= 1962 OR year = 1996

Predicate

(_exists_:year) AND year:([1955 TO 1962] OR 1996)

Interrogazioni pass-through

Il OpenSearch connettore supporta le query passthrough e utilizza il linguaggio Query DSL. Per ulteriori informazioni sull'esecuzione di query con Query DSL, consulta Query DSL nella documentazione di Elasticsearch o Query DSL nella documentazione. OpenSearch

Per utilizzare le query passthrough con il connettore, utilizzate la seguente sintassi: OpenSearch 

SELECT * FROM TABLE(
        system.query(
            schema => 'schema_name',
            index => 'index_name',
            query => "{query_string}"
        ))

Il seguente OpenSearch esempio di filtri di interrogazione passthrough per i dipendenti con status occupazionale attivo nell'employeeindice dello schema. default

SELECT * FROM TABLE(
        system.query(
            schema => 'default',
            index => 'employee',
            query => "{ ''bool'':{''filter'':{''term'':{''status'': ''active''}}}}"
        ))

Risorse aggiuntive