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 DocumentDB Il connettore DocumentDB per Amazon Athena consente ad Amazon Athena di comunicare con le istanze DocumentDB in modo da poter eseguire query sui dati DocumentDB con SQL. Il connettore funziona anche con qualsiasi endpoint compatibile con MongoDB. A differenza dei tradizionali archivi di dati relazionali, le raccolte Amazon DocumentDB non hanno uno schema prestabilito. DocumentDB non dispone di un archivio dei metadati. Ogni voce in una raccolta DocumentDB può avere campi e tipi di dati diversi. Il connettore DocumentDB supporta due meccanismi per la generazione di informazioni sullo schema della tabella: inferenza dello schema di base e metadati. AWS Glue Data Catalog L'inferenza dello schema è l'impostazione predefinita. Questa opzione esegue la scansione di un numero limitato di documenti della raccolta, forma un'unione di tutti i campi e forza i campi che hanno tipi di dati non sovrapposti. Questa opzione funziona bene per le raccolte che hanno voci per lo più uniformi. Per le raccolte con una maggiore varietà di tipi di dati, il connettore supporta il recupero dei metadati da AWS Glue Data Catalog. Se il connettore vede un AWS Glue database e una tabella che corrispondono al database DocumentDB e ai nomi delle raccolte, ottiene le informazioni sullo schema dalla tabella corrispondente AWS Glue . Quando crei la AWS Glue tabella, ti consigliamo di renderla un superset di tutti i campi a cui potresti voler accedere dalla tua raccolta DocumentDB. 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 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. ## 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). ## Parameters Utilizzare i parametri illustrati in questa sezione per configurare il connettore DocumentDB. **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. ### Connessioni Glue (consigliate) Si consiglia di configurare un connettore DocumentDB utilizzando un oggetto di connessioni Glue. Per fare ciò, impostare la variabile di ambiente `glue_connection` del connettore Lambda DocumentDB 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 DOCUMENTDB ``` **Proprietà dell’ambiente Lambda** + **glue\$1connection**: specifica il nome della connessione Glue associata al connettore federato. **Nota** Tutti i connettori che utilizzano le connessioni Glue devono essere utilizzati Gestione dei segreti AWS per memorizzare le credenziali. Il connettore DocumentDB creato utilizzando le connessioni Glue non supporta l’uso di un gestore multiplexing. Il connettore DocumentDB creato utilizzando le connessioni Glue supporta solo 2 `ConnectionSchemaVersion`. ### Connessioni legacy + **spill\$1bucket**: specifica il bucket Amazon S3 per i dati che superano i limiti della funzione Lambda. + **spill\$1prefix**: (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\$1put\$1request\$1headers**: (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\$1key\$1id**: (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\$1spill\$1encryption**: (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\$1glue** — (Facoltativo) Se presente e impostato su true, il connettore non tenta di recuperare metadati supplementari da. AWS Glue + **glue\$1catalog**: (facoltativo) utilizza questa opzione per specificare un [catalogo AWS Glue multi-account](data-sources-glue-cross-account.md). Per impostazione predefinita, il connettore tenta di ottenere metadati dal proprio account. AWS Glue + **default\$1docdb**: se presente, specifica una stringa di connessione DocumentDB da utilizzare quando non esiste alcuna variabile di ambiente specifica del catalogo. + **disable\$1projection\$1and\$1casing**: (facoltativo) disabilita la proiezione e la formattazione delle maiuscole. Usa questa opzione se desideri eseguire query sulle tabelle Amazon DocumentDB che utilizzano nomi di colonna con distinzione tra maiuscole e minuscole. Il parametro `disable_projection_and_casing` utilizza i seguenti valori per specificare il comportamento di formattazione di maiuscole e minuscole e della mappatura delle colonne: + **false**: si tratta dell'impostazione di default. La proiezione è abilitata e il connettore prevede che tutti i nomi delle colonne siano in minuscolo. + **true**: disabilita la proiezione e la combinazione di maiuscole e minuscole. Quando utilizzi il parametro `disable_projection_and_casing`, tieni presente i seguenti punti: + L'utilizzo del parametro può comportare un consumo maggiore di larghezza di banda. Inoltre, se la funzione Lambda non si trova nella stessa Regione AWS dell'origine dati, i costi di trasferimento standard tra Regioni AWS saranno più elevati a causa del maggiore utilizzo della larghezza di banda. Per ulteriori informazioni sui costi di trasferimento tra regioni, consulta la sezione Costi di [trasferimento AWS dei dati per le architetture server e serverless](https://aws.amazon.com/blogs/apn/aws-data-transfer-charges-for-server-and-serverless-architectures/) nel blog di Partner Network. AWS + Dato che viene trasferito un numero maggiore di byte e poiché un numero maggiore di byte richiede un tempo di deserializzazione maggiore, la latenza complessiva può aumentare. + **enable\$1case\$1insensitive\$1match**: (Facoltativo) quando `true`, esegue ricerche senza distinzione tra maiuscole e minuscole su nomi di schemi e tabelle in Amazon DocumentDB. Il valore predefinito è `false`. Utilizzalo se la tua query contiene nomi di schemi o tabelle in maiuscolo. #### Specifica delle stringhe di connessione Puoi specificare una o più proprietà che definiscono i dettagli di connessione DocumentDB per le istanze DocumentDB utilizzate con il connettore. A tale scopo, imposta una variabile di ambiente Lambda che corrisponda al nome del catalogo che desideri utilizzare in Athena. Ad esempio, supponiamo di voler utilizzare le seguenti query per interrogare due diverse istanze DocumentDB da Athena: ``` SELECT * FROM "docdb_instance_1".database.table ``` ``` SELECT * FROM "docdb_instance_2".database.table ``` Prima di poter utilizzare queste due istruzioni SQL, devi aggiungere due variabili di ambiente alla funzione Lambda: `docdb_instance_1` e `docdb_instance_2`. Il valore di ciascuno deve essere una stringa di connessione DocumentDB nel formato seguente: ``` mongodb://:@:/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0 ``` ##### Utilizzo dei segreti Facoltativamente, puoi utilizzare in parte o in tutto il valore Gestione dei segreti AWS per i dettagli della stringa di connessione. Per utilizzare la funzione Athena Federated Query con Secrets Manager, il VPC collegato alla funzione Lambda dovrebbe disporre dell'[accesso a Internet](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/) o di un [endpoint VPC](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) per connettersi a Secrets Manager. Se si utilizza la sintassi `${my_secret}` per inserire il nome di un segreto di Secrets Manager nella stringa di connessione, il connettore sostituisce esattamente `${my_secret}` con il valore di testo semplice di Secrets Manager. I segreti devono essere archiviati come segreti di testo semplice con valore `:`. I segreti memorizzati come `{username:,password:}` non verranno passati correttamente alla stringa di connessione. I segreti possono essere utilizzati esclusivamente anche per l'intera stringa di connessione e il nome utente e la password possono essere definiti all'interno del segreto. Ad esempio, supponiamo di impostare la variabile di ambiente Lambda per `docdb_instance_1` sul seguente valore: ``` mongodb://${docdb_instance_1_creds}@myhostname.com:123/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0 ``` L'SDK Athena Query Federation tenta automaticamente di recuperare un segreto denominato `docdb_instance_1_creds` da Secrets Manager e inietta quel valore al posto di `${docdb_instance_1_creds}`. Qualsiasi parte della stringa di connessione racchiusa entro la combinazione di caratteri `${ }` viene interpretata come un segreto da Secrets Manager. Se specifichi un nome del segreto che il connettore non riesce a trovare in Secrets Manager, il connettore non sostituisce il testo. ## Recupero dei metadati supplementari Per recuperare metadati supplementari, seguire questi passaggi per configurare il database e la tabella Glue. ### Configurazione del database Glue 1. Crea un database Glue con lo stesso nome della tua raccolta DocumentDB. 1. Nel campo Location URI, immettete `docdb-metadata-flag`. ### Configurazione della tabella Glue Aggiungere i seguenti parametri alla tabella Glue: + `docdb-metadata-flag = true` + `columnMapping = apple=APPLE` In questo esempio, `apple` rappresenta il nome della colonna in minuscolo in Glue e `APPLE` rappresenta il nome effettivo della colonna con distinzione tra maiuscole e minuscole nella raccolta DocumentDB. ### Verifica del recupero dei metadati 1. Eseguire la query. 1. Controlla i CloudWatch log della funzione Lambda per il corretto recupero dei metadati. Un recupero riuscito mostrerà la seguente voce di registro: ``` doGetTable: Retrieved schema for table[TableName{schemaName=test, tableName=profiles}] from AWS Glue. ``` **Nota** Se la tabella ha già un campo `columnMapping` configurato, è sufficiente aggiungere il parametro `docdb-metadata-flag = true` alle proprietà della tabella. ## Configurazione di database e tabelle in AWS Glue Poiché la funzionalità di inferenza dello schema integrata nel connettore esegue la scansione di un numero limitato di documenti e supporta solo un sottoinsieme di tipi di dati, è consigliabile utilizzarla invece AWS Glue per i metadati. Per abilitare una AWS Glue tabella da utilizzare con Amazon DocumentDB, devi disporre di un database e di una tabella per il AWS Glue database e la raccolta DocumentDB per i quali desideri fornire metadati supplementari. **Per utilizzare una tabella per metadati supplementari AWS Glue** 1. Usa la AWS Glue console per creare un AWS Glue database con lo stesso nome del database Amazon DocumentDB. 1. Imposta la proprietà URI del database da includere **docdb-metadata-flag**. 1. (Facoltativo) Aggiungi la proprietà della tabella **sourceTable**. Questa proprietà definisce il nome della tabella di origine in Amazon DocumentDB. Usa questa proprietà se la AWS Glue tabella ha un nome diverso dal nome della tabella in Amazon DocumentDB. Le differenze nelle regole di denominazione tra Amazon DocumentDB AWS Glue e Amazon DocumentDB possono renderlo necessario. Ad esempio, le lettere maiuscole non sono consentite nei nomi AWS Glue delle tabelle, ma sono consentite nei nomi delle tabelle di Amazon DocumentDB. 1. (Facoltativo) Aggiungi la proprietà della tabella **columnMapping**. Questa proprietà definisce le mappature dei nomi delle colonne. Utilizza questa proprietà se le regole di denominazione delle AWS Glue colonne impediscono di creare una AWS Glue tabella con gli stessi nomi di colonna di quelli della tabella Amazon DocumentDB. Ciò può essere utile perché le lettere maiuscole sono consentite nei nomi delle colonne Amazon DocumentDB, ma non sono permesse nei nomi delle colonne AWS Glue . Il valore della proprietà `columnMapping` dovrebbe essere un insieme di mappature nel formato `col1=Col1,col2=Col2`. **Nota** Il mapping di colonne si applica solo ai nomi delle colonne di primo livello e non ai campi annidati. Dopo aver aggiunto la proprietà AWS Glue `columnMapping` table, puoi rimuovere la variabile di ambiente `disable_projection_and_casing` Lambda. 1. Assicurati di utilizzare i tipi di dati AWS Glue appropriati elencati in questo documento. ## Supporto dei tipi di dati Questa sezione elenca i tipi di dati utilizzati dal connettore DocumentDB per l'inferenza dello schema e i tipi di dati quando vengono utilizzati i AWS Glue metadati. ### Tipi di dati di inferenza dello schema La funzionalità di inferenza dello schema del connettore DocumentDB tenta di dedurre i valori come appartenenti a uno dei seguenti tipi di dati. Nella tabella seguente vengono illustrati i tipi di dati corrispondenti per Amazon DocumentDB, Java e Apache Arrow. **** | Apache Arrow | Java o DocDB | | --- | --- | | VARCHAR | Stringa | | INT | Numero intero | | BIGINT | Long | | BIT | Booleano | | FLOAT4 | Float | | FLOAT8 | Double | | TIMESTAMPSEC | Data | | VARCHAR | ObjectId | | LIST | List | | STRUCT | Documento | ### AWS Glue tipi di dati Se si utilizzano AWS Glue metadati supplementari, è possibile configurare i seguenti tipi di dati. La tabella mostra i tipi di dati corrispondenti per AWS Glue e Apache Arrow. **** | AWS Glue | Apache Arrow | | --- | --- | | int | INT | | bigint | BIGINT | | virgola mobile a doppia precisione | FLOAT8 | | virgola mobile | FLOAT4 | | booleano | BIT | | binary | VARBINARY | | stringa | VARCHAR | | List | LIST | | Struct | STRUCT | ## Autorizzazioni richieste Consulta la sezione `Policies` del file [athena-docdb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-docdb/athena-docdb.yaml) per i dettagli completi delle policy IAM richieste da questo connettore. L'elenco che segue riporta un riepilogo delle autorizzazioni richieste. + **Accesso in scrittura ad Amazon S3**: per trasferire i risultati di query di grandi dimensioni, il connettore richiede l'accesso in scrittura a una posizione in Amazon S3. + **Athena GetQueryExecution**: il connettore utilizza questa autorizzazione per fallire rapidamente quando la query Athena upstream è terminata. + **AWS Glue Data Catalog**— Il connettore DocumentDB richiede l'accesso in sola lettura per AWS Glue Data Catalog ottenere informazioni sullo schema. + **CloudWatch Registri**: il connettore richiede l'accesso ai CloudWatch registri per l'archiviazione dei registri. + **Gestione dei segreti AWS accesso in lettura**: se si sceglie di archiviare i dettagli degli endpoint di DocumentDB in Secrets Manager, è necessario concedere al connettore l'accesso a tali segreti. + **Accesso VPC**: il connettore richiede la capacità di collegare e scollegare le interfacce al VPC in modo che possa connettersi ad esso e comunicare con le istanze DocumentDB. ## Performance Il connettore Amazon DocumentDB per Athena al momento non supporta le scansioni in parallelo, ma tenta di eseguire il pushdown dei predicati come parte delle query DocumentDB e i predicati sugli indici della raccolta DocumentDB risultano in una quantità di dati scansionati significativamente inferiore. La funzione Lambda esegue il pushdown dei predicati per ridurre la quantità di dati scansionati dalla query. Tuttavia, la selezione di un sottoinsieme di colonne a volte comporta un runtime delle query più lungo. Le clausole `LIMIT` riducono la quantità di dati scansionati, ma se non viene fornito un predicato, le query `SELECT` con una clausola `LIMIT` eseguiranno la scansione di almeno 16 MB di dati. ## Query passthrough Il connettore Amazon DocumentDB Athenasupporta le [query passthrough](federated-query-passthrough.md) ed è basato su NoSQL. Per ulteriori informazioni sull’esecuzione di query in Amazon DocumentDB, consultare [Esecuzione query](https://docs.aws.amazon.com/documentdb/latest/developerguide/querying.html) nella *Guida per gli sviluppatori Amazon DocumentDB.* Per utilizzare query passthrough con Amazon DocumentDB, utilizzare la seguente sintassi: ``` SELECT * FROM TABLE( system.query( database => 'database_name', collection => 'collection_name', filter => '{query_syntax}' )) ``` L’esempio seguente interroga il database `example` all’interno della raccolta`TPCDS`, filtrando tutti i libri con il titolo *Bill of Rights*. ``` SELECT * FROM TABLE( system.query( database => 'example', collection => 'tpcds', filter => '{title: "Bill of Rights"}' )) ``` ## Risorse aggiuntive + *Per un articolo sull'utilizzo di [Amazon Athena Federated Query per connettere un database MongoDB a Quick](federated-queries.md) per creare dashboard e visualizzazioni, consulta Visualizzare i dati [MongoDB da [Quick](https://aws.amazon.com/quicksight/) utilizzando Amazon Athena Federated Query nel Big Data Blog](https://aws.amazon.com/blogs/big-data/visualize-mongodb-data-from-amazon-quicksight-using-amazon-athena-federated-query/).AWS * + [Per ulteriori informazioni su questo connettore, visita il sito corrispondente su .com.](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-docdb) GitHub