Eseguire la migrazione da CouchBase ad Azure Cosmos DB for NoSQL

Articolo
08/15/2024

SI APPLICA A: NoSQL

Azure Cosmos DB è un database scalabile, distribuito a livello globale e completamente gestito. Offre un accesso ai dati con bassa latenza garantita. Per altre informazioni su Azure Cosmos DB, vedere l'articolo Panoramica. Questo articolo fornisce istruzioni per eseguire la migrazione di applicazioni Java connesse a Couchbase a un account API per NoSQL in Azure Cosmos DB.

Differenze nella nomenclatura

Di seguito sono riportate le funzionalità chiave che funzionano in modo diverso in Azure Cosmos DB rispetto a Couchbase:

Couchbase	Azure Cosmos DB
Server Couchbase	Conto
Bucket	Database
Bucket	Contenitore/raccolta
Documento JSON	Elemento/documento

Differenze principali

Azure Cosmos DB dispone di un campo "ID" all'interno del documento, mentre in Couchbase l'ID è incluso nel bucket. Il campo "ID" è univoco nell'intera partizione.
Azure Cosmos DB esegue il ridimensionamento mediante la tecnica di partizionamento o partizionamento orizzontale, suddividendo quindi i dati in più partizioni/partizioni di database. Queste partizioni/partizioni di database vengono create in base alla proprietà della chiave di partizione fornita. È possibile selezionare la chiave di partizione per ottimizzare le operazioni di lettura e scrittura o anche di lettura/scrittura ottimizzata. Per altre informazioni, vedere l'articolo sul partizionamento.

In Azure Cosmos DB non è necessario che la gerarchia di primo livello indichi la raccolta perché il nome della raccolta esiste già. Questa funzionalità semplifica la struttura JSON. Di seguito è riportato un esempio che mostra le differenze nel modello di dati tra Couchbase e Azure Cosmos DB:

Couchbase: ID documento = "99FF4444"

{
  "TravelDocument":
  {
    "Country":"India",
    "Validity" : "2022-09-01",
    "Person":
    {
      "Name": "Manish",
      "Address": "AB Road, City-z"
    },
    "Visas":
    [
      {
      "Country":"India",
      "Type":"Multi-Entry",
      "Validity":"2022-09-01"
      },
      {
      "Country":"US",
      "Type":"Single-Entry",
      "Validity":"2022-08-01"
      }
    ]
  }
}

Azure Cosmos DB: vedere "ID" all'interno del documento, come illustrato di seguito

{
  "id" : "99FF4444",

  "Country":"India",
   "Validity" : "2022-09-01",
    "Person":
    {
      "Name": "Manish",
      "Address": "AB Road, City-z"
    },
    "Visas":
    [
      {
      "Country":"India",
      "Type":"Multi-Entry",
      "Validity":"2022-09-01"
      },
      {
      "Country":"US",
      "Type":"Single-Entry",
      "Validity":"2022-08-01"
      }
    ]
  }

Supporto SDK per Java

Azure Cosmos DB include sdk (Software Development Kit) seguenti per supportare framework Java diversi:

SDK asincrono
SDK Spring Boot

Le sezioni seguenti descrivono quando usare ognuno di questi SDK. Si consideri un esempio in cui sono disponibili tre tipi di carichi di lavoro:

Couchbase come repository di documenti e query personalizzate basate su dati Spring

Se il carico di lavoro di cui si esegue la migrazione si basa su Spring Boot Based SDK, è possibile seguire questa procedura:

Aggiungere l'elemento padre al file POM.xml:

<parent>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-parent</artifactId>
   <version>2.1.5.RELEASE</version>
   <relativePath/>
</parent>

Aggiungere proprietà al file POM.xml:
```
<azure.version>2.1.6</azure.version>
```

Aggiungere dipendenze al file POM.xml:

<dependency>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>azure-cosmosdb-spring-boot-starter</artifactId>
    <version>2.1.6</version>
</dependency>

Aggiungere proprietà dell'applicazione nelle risorse e specificare quanto segue. Assicurarsi di sostituire i parametri URL, chiave e nome del database:
```
   azure.cosmosdb.uri=<your-cosmosDB-URL>
   azure.cosmosdb.key=<your-cosmosDB-key>
   azure.cosmosdb.database=<your-cosmosDB-dbName>
```

Definire il nome della raccolta nel modello. È anche possibile specificare altre annotazioni. Ad esempio, ID e chiave di partizione per identificarli in modo esplicito:

@Document(collection = "mycollection")
    public class User {
        @id
        private String id;
        private String firstName;
        @PartitionKey
        private String lastName;
    }

Di seguito sono riportati i frammenti di codice per le operazioni CRUD:

Operazioni di inserimento e aggiornamento

Dove _repo è l'oggetto del repository e doc è l'oggetto della classe POJO. È possibile usare .save per inserire o eseguire l'upsert (se è stato trovato un documento con l'ID specificato). Nel frammento di codice seguente viene illustrato come inserire o aggiornare un oggetto Doc:

_repo.save(doc);

Operazione Elimina

Si consideri il frammento di codice seguente, in cui l'oggetto Doc avrà l'ID e la chiave di partizione obbligatori per individuare ed eliminare l'oggetto:

_repo.delete(doc);

Operazione di lettura

È possibile leggere il documento specificando o meno la chiave di partizione. Se non si specifica la chiave di partizione, viene considerata come una query tra partizioni. Si considerino gli esempi di codice seguenti: il primo esegue l'operazione usando i campi ID e Chiave di partizione. Nel secondo esempio viene usato un campo normale, senza specificare il campo Chiave di partizione.

_repo.findByIdAndName(objDoc.getId(),objDoc.getName());
_repo.findAllByStatus(objDoc.getStatus());

A questo punto, è possibile usare l'applicazione con Azure Cosmos DB. Il codice di esempio completo per l'esempio descritto in questo documento è disponibile nel repository CouchbaseToCosmosDB-SpringCosmos di GitHub.

Couchbase come repository di documenti e uso di query N1QL

Le query N1QL permettono di definire le query in Couchbase.

Query N1QL	Query di Azure Cosmos DB
SELECT META(`TravelDocument`).id AS id, `TravelDocument`.* FROM `TravelDocument` WHERE `_type` = "com.xx.xx.xx.xxx.xxx.xxxx " and country = 'India’ and ANY m in Visas SATISFIES m.type == 'Multi-Entry' and m.Country IN ['India', Bhutan’] ORDER BY `Validity` DESC LIMIT 25 OFFSET 0	SELECT c.id,c FROM c JOIN m in c.country=’India’ WHERE c._type = " com.xx.xx.xx.xxx.xxx.xxxx" and c.country = 'India' and m.type = 'Multi-Entry' and m.Country IN ('India', 'Bhutan') ORDER BY c.Validity DESC OFFSET 0 LIMIT 25

Nelle query N1QL è possibile notare le modifiche seguenti:

Non è necessario usare la parola chiave META o fare riferimento al documento di primo livello. È invece possibile creare un riferimento personalizzato al contenitore. In questo esempio, è stato considerato come "c" (può trattarsi di qualsiasi elemento). Questo riferimento viene usato come prefisso per tutti i campi di primo livello. Ad esempio c.id, c.paese e così via.
Invece di "ANY", è ora possibile creare un join in un sottodocumento e riferirsi ad esso con un alias dedicato come "m". Dopo aver creato l'alias per un documento secondario, è necessario usarlo. Ad esempio, m.Paese.
La sequenza di OFFSET è diversa nella query di Azure Cosmos DB. Innanzitutto, è necessario specificare i valori OFFSET e quindi LIMIT. È consigliabile non usare Spring Data SDK se si usano le query definite massime personalizzate perché può avere un sovraccarico non necessario sul lato client durante il passaggio della query ad Azure Cosmos DB. È invece disponibile un SDK di Java asincrono diretto, che può essere usato in modo molto efficiente in questo caso.

Operazione di lettura

Usare l'SDK asincrono per Java con i passaggi seguenti:

Configurare la dipendenza seguente nel file POM.xml:

<!-- https://mvnrepository.com/artifact/com.microsoft.azure/azure-cosmosdb -->
<dependency>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
    <version>3.0.0</version>
</dependency>

Creare un oggetto Connection per Azure Cosmos DB usando il metodo ConnectionBuilder, come illustrato nell'esempio seguente. Assicurarsi di inserire questa dichiarazione nel bean, in modo che il codice seguente venga eseguito una sola volta:

ConnectionPolicy cp=new ConnectionPolicy();
cp.connectionMode(ConnectionMode.DIRECT);

if(client==null)
   client= CosmosClient.builder()
      .endpoint(Host)//(Host, PrimaryKey, dbName, collName).Builder()
       .connectionPolicy(cp)
       .key(PrimaryKey)
       .consistencyLevel(ConsistencyLevel.EVENTUAL)
       .build();

container = client.getDatabase(_dbName).getContainer(_collName);

Per eseguire la query, è necessario eseguire il frammento di codice seguente:

Flux<FeedResponse<CosmosItemProperties>> objFlux= container.queryItems(query, fo);

A questo punto, con l'aiuto del metodo precedente, è possibile passare più query ed eseguirle senza problemi. Se si ha la necessità di eseguire una query di grandi dimensioni che può essere suddivisa in più query, provare il frammento di codice seguente anziché quello precedente:

for(SqlQuerySpec query:queries)
{
   objFlux= container.queryItems(query, fo);
   objFlux .publishOn(Schedulers.elastic())
         .subscribe(feedResponse->
            {
               if(feedResponse.results().size()>0)
               {
                  _docs.addAll(feedResponse.results());
               }
            
            },
            Throwable::printStackTrace,latch::countDown);
   lstFlux.add(objFlux);
}
                  
      Flux.merge(lstFlux);
      latch.await();
}

Con il codice precedente, è possibile eseguire query in parallelo e aumentare le esecuzioni distribuite da ottimizzare. È anche possibile eseguire le operazioni di inserimento e aggiornamento:

Operazioni di inserimento

Per inserire il documento, eseguire il codice seguente:

Mono<CosmosItemResponse> objMono= container.createItem(doc,ro);

Eseguire quindi la sottoscrizione a Mono come:

CountDownLatch latch=new CountDownLatch(1);
objMono .subscribeOn(Schedulers.elastic())
        .subscribe(resourceResponse->
        {
           if(resourceResponse.statusCode()!=successStatus)
              {
                 throw new RuntimeException(resourceResponse.toString());
              }
           },
        Throwable::printStackTrace,latch::countDown);
latch.await();

Operazione di upsert

Per l'operazione di upsert è necessario specificare il documento da aggiornare. Per recuperare il documento completo, è possibile usare il frammento indicato nell'operazione di lettura dell'intestazione, per poi modificare i campi necessari. Il seguente frammento di codice esegue l'upsert del documento:

Mono<CosmosItemResponse> obs= container.upsertItem(doc, ro);

Eseguire quindi la sottoscrizione a Mono. Vedere il frammento di sottoscrizione Mono nell'operazione di inserimento.

Operazioni di eliminazione

Il frammento di codice seguente esegue l'operazione di eliminazione:

CosmosItem objItem= container.getItem(doc.Id, doc.Tenant);
Mono<CosmosItemResponse> objMono = objItem.delete(ro);

Eseguire quindi la sottoscrizione a Mono; vedere il frammento di sottoscrizione Mono nell'operazione di inserimento. L'esempio di codice completo è disponibile nel repository CouchbaseToCosmosDB-AsyncInSpring di GitHub.

Couchbase come coppia chiave/valore

Si tratta di un tipo semplice di carico di lavoro in cui è possibile eseguire ricerche anziché query. Per le coppie chiave/valore, usare la procedura seguente:

Provare a usare "/ID" come chiave primaria, in modo da garantire che sia possibile eseguire l'operazione di ricerca direttamente nella partizione specifica. Creare una raccolta e specificare "/ID" come chiave di partizione.
Disattivare completamente l'indicizzazione. Poiché si eseguiranno operazioni di ricerca, non si verifica alcun sovraccarico di indicizzazione. Per disattivare l'indicizzazione, accedere al portale di Azure e passare all'account di Azure Cosmos DB. Aprire Esplora dati, selezionare il Database e il Contenitore. Aprire la scheda Scalabilità e impostazioni e selezionare Criteri di indicizzazione. Attualmente, i criteri di indicizzazione hanno un aspetto simile al seguente:
```
{
 "indexingMode": "consistent",
 "automatic": true,
 "includedPaths": [
     {
         "path": "/*"
     }
 ],
 "excludedPaths": [
     {
         "path": "/\"_etag\"/?"
     }
 ]
 }
```
Sostituire i criteri di indicizzazione sopra indicati con i criteri seguenti:
```
{
 "indexingMode": "none",
 "automatic": false,
 "includedPaths": [],
 "excludedPaths": []
 }
```

Per creare un oggetto Connection, usare il frammento di codice seguente. Oggetto Connection (da inserire in @Bean o rendere statico):

ConnectionPolicy cp=new ConnectionPolicy();
cp.connectionMode(ConnectionMode.DIRECT);

if(client==null)
   client= CosmosClient.builder()
      .endpoint(Host)//(Host, PrimaryKey, dbName, collName).Builder()
       .connectionPolicy(cp)
       .key(PrimaryKey)
       .consistencyLevel(ConsistencyLevel.EVENTUAL)
       .build();

container = client.getDatabase(_dbName).getContainer(_collName);

A questo punto è possibile eseguire le operazioni CRUD, come indicato di seguito:

Operazione di lettura

Per leggere l'elemento, usare il frammento di codice seguente:

CosmosItemRequestOptions ro=new CosmosItemRequestOptions();
ro.partitionKey(new PartitionKey(documentId));
CountDownLatch latch=new CountDownLatch(1);
      
var objCosmosItem= container.getItem(documentId, documentId);
Mono<CosmosItemResponse> objMono = objCosmosItem.read(ro);
objMono .subscribeOn(Schedulers.elastic())
        .subscribe(resourceResponse->
        {
           if(resourceResponse.item()!=null)
           {
              doc= resourceResponse.properties().toObject(UserModel.class);
           }
        },
        Throwable::printStackTrace,latch::countDown);
latch.await();

Operazioni di inserimento

Per inserire un elemento, è possibile eseguire il codice seguente:

Mono<CosmosItemResponse> objMono= container.createItem(doc,ro);

Eseguire quindi la sottoscrizione a Mono come:

CountDownLatch latch=new CountDownLatch(1);
objMono.subscribeOn(Schedulers.elastic())
      .subscribe(resourceResponse->
      {
         if(resourceResponse.statusCode()!=successStatus)
            {
               throw new RuntimeException(resourceResponse.toString());
            }
         },
      Throwable::printStackTrace,latch::countDown);
latch.await();

Operazione di upsert

Per aggiornare il valore di un elemento, fare riferimento al frammento di codice seguente:

Mono<CosmosItemResponse> obs= container.upsertItem(doc, ro);

Eseguire quindi la sottoscrizione a Mono; vedere il frammento di sottoscrizione Mono nell'operazione di inserimento.

Operazioni di eliminazione

Usare il frammento di codice seguente per eseguire l'operazione di eliminazione:

CosmosItem objItem= container.getItem(id, id);
Mono<CosmosItemResponse> objMono = objItem.delete(ro);

Migrazione dati

Usare Azure Data Factory per eseguire la migrazione dei dati. Si tratta del metodo più consigliato per eseguire la migrazione dei dati. Configurare l'origine come Couchbase ed eseguire il sink come Azure Cosmos DB for NoSQL. Per la procedura dettagliata, vedere l'articolo Connettore Data Factory di Azure Cosmos DB.

Passaggi successivi

Per un esempio, vedere Test delle prestazioni e della scalabilità con Azure Cosmos DB.
Per ottimizzare il codice, vedere l'articolo Suggerimenti sulle prestazioni per Azure Cosmos DB.
Esplorare il repository di GitHub riferimenti SDK per l'SDK asincrono per Java V3.

Condividi tramite

Eseguire la migrazione da CouchBase ad Azure Cosmos DB for NoSQL

Differenze nella nomenclatura

Differenze principali

Supporto SDK per Java

Couchbase come repository di documenti e query personalizzate basate su dati Spring

Operazioni di inserimento e aggiornamento

Operazione Elimina

Operazione di lettura

Couchbase come repository di documenti e uso di query N1QL

Operazione di lettura

Operazioni di inserimento

Operazione di upsert

Operazioni di eliminazione

Couchbase come coppia chiave/valore

Operazione di lettura

Operazioni di inserimento

Operazione di upsert

Operazioni di eliminazione

Migrazione dati

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive