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 Questo connettore può essere registrato con Catalogo Dati Glue 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 connessioni Glue per centralizzare le proprietà di configurazione in Glue. **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 + Implementa il connettore sul tuo Account AWS utilizzando la console Athena o AWS Serverless Application Repository. Per ulteriori informazioni, consulta [Crea una connessione di un'origine dati](connect-to-a-data-source.md) o [Utilizzare il AWS Serverless Application Repository per distribuire un connettore di origine dati](connect-data-source-serverless-app-repo.md). ## 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](https://opensearch.org/docs/latest/dashboards/im-dashboards/datastream/) nella OpenSearch documentazione e [Introduzione ai flussi di dati](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/data-streams.html#data-streams-example) 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](#connectors-opensearch-setting-up-databases-and-tables-in-aws-glue). ## Parameters Utilizzate i parametri di questa sezione per configurare il OpenSearch connettore. **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à diconnessione AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html) corrispondenti. Dal 3 dicembre 2024, utilizzare i parametri seguenti solo quando si [implementa manualmente](connect-data-source-serverless-app-repo.md) una versione precedente di un connettore di origine dati Athena. ### AWS Glue Data Catalog connettori federati Si consiglia di configurare un OpenSearch connettore utilizzando un oggetto Glue connections. Per fare ciò, imposta la variabile di `glue_connection` ambiente del OpenSearch connettore Lambda sul nome della connessione Glue da utilizzare. **Proprietà delle connessioni Glue** Utilizzare il seguente comando per ottenere lo schema di un oggetto di connessione Glue. Questo schema contiene tutti i parametri che è possibile usare per controllare la connessione. ``` aws glue describe-connection-type --connection-type OPENSEARCH ``` **Proprietà dell’ambiente Lambda** Le seguenti proprietà dell'ambiente Lambda si applicano solo quando si utilizza il connettore con una funzione Lambda nel proprio account. + **glue\_connection**: specifica il nome della connessione Glue associata al connettore federato. **Nota** Tutti i connettori che utilizzano una connessione AWS Glue Data Catalog federata devono Gestione dei segreti AWS memorizzare le credenziali. Il OpenSearch connettore creato utilizzando una connessione AWS Glue Data Catalog federata non supporta l'uso di un gestore di multiplazione. Il OpenSearch connettore creato utilizzando una connessione AWS Glue Data Catalog federata supporta solo 2. `ConnectionSchemaVersion` ### Connettori federati del catalogo dati Athena + **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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) 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 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)all'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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html). + **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` Se`auto_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. Gestione dei segreti AWS `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. Gestione dei segreti AWS Il segreto deve essere archiviato nel seguente formato JSON: ``` { "username": "your_username", "password": "your_password" } ``` Il connettore analizzerà automaticamente questa struttura JSON per recuperare le credenziali. **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 [Move i segreti codificati](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) nella Guida per l'utente. Gestione dei segreti AWSGestione dei segreti AWS * 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 @. {{user\_name}} {{password}} Sebbene la password possa contenere `@` segni incorporati, la prima `@` funge da separatore da{{user\_name}}. È 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 | stringa | | Long | BIGINT | bigint | | scaled\_float | BIGINT | SCALED\_FLOAT(...) | | intero | INT | int | | short | SMALLINT | smallint | | byte | TINYINT | tinyint | | virgola mobile a doppia precisione | FLOAT8 | virgola mobile a doppia precisione | | float, half\_float | FLOAT4 | virgola mobile | | 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](#connectors-opensearch-defining-metadata-for-arrays-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 `Base64` e convertito in a. `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 si desidera eseguire la query ed {{index}} è il nome dell'indice. ``` SHOW DATABASES in `lambda:{{function_name}}` ``` ``` SHOW TABLES in `lambda:{{function_name}}`.{{domain}} ``` ``` DESCRIBE `lambda:{{function_name}}`.{{domain}}.{{index}} ``` ## Performance 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) ``` ## Query passthrough Il OpenSearch connettore supporta [le query passthrough e utilizza il linguaggio Query](federated-query-passthrough.md) DSL. [Per ulteriori informazioni sull'esecuzione di query con Query DSL, consulta Query DSL nella documentazione di Elasticsearch o [Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html) nella documentazione.](https://opensearch.org/docs/latest/query-dsl/) 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'`employee`indice dello schema. `default` ``` SELECT * FROM TABLE( system.query( schema => 'default', index => 'employee', query => "{ ''bool'':{''filter'':{''term'':{''status'': ''active''}}}}" )) ``` ## Risorse aggiuntive + *Per un articolo sull'utilizzo del OpenSearch connettore Amazon Athena per interrogare i dati in Amazon OpenSearch Service e Amazon S3 in un'unica query, [consulta Interrogare i dati in Amazon Service usando SQL di OpenSearch Amazon Athena](https://aws.amazon.com/blogs/big-data/query-data-in-amazon-opensearch-service-using-sql-from-amazon-athena/) nel Big Data Blog.AWS * + Per ulteriori informazioni su questo connettore, visita [il sito corrispondente](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-elasticsearch) su .com. GitHub