COPY TO Couchbase Data Service Statements

  • Capella Columnar
  • reference
    +
    This topic describes how you use COPY TO statements to write the results of a query—​or a copy of an entire collection—​out to a collection on Capella or Couchbase Server.

    For more information and use cases for this operation, see Copy Results to a Couchbase Collection.

    Syntax

    CopyToCouchbase EBNF
    CopyToCouchbase ::= "COPY" SourceDefinition
               "TO" CollectionQualifiedName
               "AT" LinkName
               "KEY" (KeyExpr | "AUTOGENERATED")
               ("WITH" WithClause)?
    CopyToCouchbase Diagram
    "COPY" SourceDefinition "TO" CollectionQualifiedName "AT" LinkName "KEY" (KeyExpr | "AUTOGENERATED") ("WITH" WithClause)?
    Show SourceDefinition Diagram
    ( QualifiedName | "(" Query ")" ) ("AS"? AliasIdentifier )?
    SourceDefinition
    Show CollectionQualifiedName Diagram
    NameStringLiteral
    CollectionQualifiedName
    Show KeyExpr Diagram
    Expression
    KeyExpr
    Show WithClause Diagram
    "WITH" "{" NameValuePair ("," NameValuePair )* "}"
    WithClause
    Show NameValuePair Diagram
    NameStringLiteral ":" ValueLiteral
    NameValuePair

    Examples

    This example runs a COPY TO statement on a Capella Columnar collection that shadows operational data. As a prerequisite for running this example yourself, follow the add sample data procedures to add remote collections to Capella Columnar. In a Capella operational database, you also add a target copyToTest bucket with a beer scope and a cali collection.

    This example uses the credentials stored in the capellaLink remote link to copy documents in the Capella Columnar remoteCapella.remoteBeer.beerUs collection to the Capella collection.

      COPY (
        SELECT name, city, code, website
        FROM remoteCapella.remoteBeer.beerUs
        WHERE state = "California")
        AS b
      TO copyToTest.beer.cali
      AT capellaLink
      KEY uppercase(b.name) || "-" || to_string(b.code);

    In Capella, you can query the target copyToTest.beer.cali collection to verify this operation. See Read Data and Return Results.

    Show an additional example

    This example runs a COPY TO statement on an external collection in Capella Columnar that supports queries of data in an Amazon S3 bucket. It copies to a target copyMusic bucket in a Capella operational database with a copyMusic scope and an countrySongs collection.

    This example uses credentials stored in a capellaLink remote link to copy documents in a music.myPlaylist.countrySongs collection to the Capella collection.

    As an external collection, the music.myPlaylist.countrySongs collection provides the destination path to data in an Amazon S3 bucket.

    In Capella Columnar:

      COPY music.myPlaylist.countrySongs
        TO copyMusic.myPlaylist.countrySongs
        AT capellaLink
        KEY AUTOGENERATED;

    The result is a complete copy of data in the Amazon S3 bucket referenced by music.myPlaylist.countrySongs in a Capella collection in JSON format.

    In Capella, you can query the target copyMusic.myPlaylist.countrySongs collection to verify this operation. See Read Data and Return Results.

    Arguments

    SourceDefinition

    As the source, you specify either the fully qualified name of a Capella Columnar collection or a query.

    • If you specify a Capella Columnar collection name, then the whole collection—or view or synonym—is the source of data to copy.

    • If you specify a query, then the result of that query is the source of data.

    TO

    The TO clause identifies the fully qualified name of a collection on Capella or Couchbase Server.

    AT

    The AT clause specifies the name of the Capella Columnar link that contains credentials for accessing the Capella operational database or Couchbase Server cluster.

    KEY

    The KEY evaluates to be the key for each document in the Capella or Couchbase Server collection. For the KeyExpr you can provide:

    • The name of a key (field) found in the source documents.

    • An expression that evaluates to a string, and that can involve multiple keys and functions.

    • AUTOGENERATED, which generates a UUID.