---
title: COPY TO Couchbase Data Service Statements
description: This topic describes how you use <code>COPY TO</code> statements to
  write the results of a query--or a copy of an entire collection--out to a
  collection on Capella or Couchbase Server.
pubDate: 2026-08-17T09:53:44.266Z
antora:
  editUrl: https://github.com/couchbaselabs/docs-columnar/edit/main/modules/sqlpp/pages/5_dml_copy_to_kv.adoc
  xref: xref:analytics:sqlpp:5_dml_copy_to_kv.adoc[]
---

[Consult the llms.txt file for a full list of contents](/llms.txt)
[View original HTML](/analytics/sqlpp/5_dml_copy_to_kv.html)

# COPY TO Couchbase Data Service Statements

> 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](../query/copy-to-kv.md).

## [](#syntax)Syntax

**CopyToCouchbase EBNF** 

```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)?](_images/CopyToCouchbase.png) 

**Show SourceDefinition Diagram** 

![( QualifiedName | "(" Query ")" ) ("AS"? AliasIdentifier )?](_images/SourceDefinition.png) 

SourceDefinition

**Show CollectionQualifiedName Diagram** 

![NameStringLiteral](_images/CollectionQualifiedName.png) 

CollectionQualifiedName

**Show KeyExpr Diagram** 

![Expression](_images/KeyExpr.png) 

KeyExpr

**Show WithClause Diagram** 

!["WITH" "{" NameValuePair ("," NameValuePair )* "}"](_images/WithClause.png) 

WithClause

**Show NameValuePair Diagram** 

![NameStringLiteral ":" ValueLiteral](_images/NameValuePair.png) 

NameValuePair

## [](#examples)Examples

This example runs a COPY TO statement on a Capella Analytics collection that shadows operational data. As a prerequisite for running this example yourself, follow the [add sample data](../intro/examples.md) procedures to add remote collections to Capella Analytics. 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 Analytics `remoteCapella.remoteBeer.beerUs` collection to the Capella collection.

```SQL++
  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](../../cloud/guides/select.md).

**Show an additional example** 

This example runs a COPY TO statement on an external collection in Capella Analytics 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 Analytics:

```SQL++
  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](../../cloud/guides/select.md).

## [](#arguments)Arguments

SourceDefinition

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

* If you specify a Capella Analytics 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 Analytics 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.

See [Introduction: Document Keys](../../cloud/indexes/indexing-and-query-perf.md#introduction-document-keys).

## [](#see-also)See Also

* [Copy Results to a Couchbase Collection](../query/copy-to-kv.md)
* [Stream Data from Remote Sources](../sources/manage-remote.md)
* [Access Data](../intro/examples.md)
* [Environment and Identifier Functions](8%5Fbuiltin%5Fenv.md)