Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Import Data with the Capella UI

  • Capella Operational
    March 23, 2025
    + 12
    Use the Capella Import page to import data from your local drive into your cluster. The Capella Import page guides you through each step of the process, prompting you to select source files and identify target locations. Capella prepares a preview of your import, displaying real-time updates as you explore options for refining your import. Using preview, you can ensure you’re satisfied with the import before importing data into your cluster.

    About Importing Data

    Choose one of these options when importing data using the Capella UI:

    • Import data sets smaller than 40 MB from your browser.

    • Generate a command to import larger datasets using cbimport.

    • Explore Capella using sample data.

    Required Permissions

    You must have the Cluster Data Reader/Writer role to be able to import data.

    Source Files

    The Capella UI lets you import source files that reside on your local machine. Capella supports importing these file formats:

    • CSV — Comma-separated values file.

    • TSV — Tab-separated values file.

    • JSON — JavaScript Object Notation file.

    • JSONL — JSON Lines file, a structured data storage format where each line is treated as an independent, valid JSON object.

    Cluster Target Locations

    You can specify existing Scopes and Collections for your data import target. You can also create new ones as you set up the import.

    Reviewing and Refining Your Import

    Once you’ve specified your source file and target location, you can explore options for creating document keys and specify what parts of the data should be imported using Import Rules.

    Options for Creating Document Keys

    Each document extracted from your imported files needs a document key. You can choose to let Capella generate keys randomly for each document or specify a field value from your dataset for the document key. You can also choose to add a custom expression to generate document keys.

    Use any of the following components to create custom document keys.

    Document Key Component Description Delimiter

    UUID

    Universally Unique Identifier generator

    # (hash)

    MONO_INCR

    Monotonically increasing number generator

    # (hash)

    Field values

    The value of a field selected from your data set

    % (percent)

    For example, the expression #UUID#_%City%_#MONO_INCR# generates the following document key:

    "docId": "6e41a1b1-c876-481a-afa0-aab395cadce2_Leominster_1",

    Import Rules

    Using import rules, you can control which portions of your source file are included in the import.

    • Skip the first n documents: by default, all documents are loaded. Setting this option skips a specified number of documents before importing. When enabled, enter the number of documents to skip before the import starts.

    • Import a maximum of n documents: stop loading after a specified number of documents. Use this to partially load large datasets. When enabled, enter the maximum number of documents to import.

    • Exclude field names: Omit named fields from the uploaded documents. Use this to remove a field from documents, for example, a document key from a field in a document. When enabled, specify a comma-separated list of field names to exclude from the import.

    How to Import Data

    Follow the steps in the Capella UI to populate your cluster.

    To access the Import tool, go to Data Tools  Import.

    In free tier accounts, the Home tab also has a link to the Import tool.

    Import Data from Your Browser

    Import a single file smaller than 40MB.

    1. Go to Data Tools  Import.

    2. Choose Load from your browser.

    3. Choose a file to upload or drag-and-drop it into the UI.

    4. Specify the target for your import. You can choose existing Scopes and Collections or create new ones.

    5. Preview and refine your import by:

      1. Choosing how to create document keys.

      2. Configuring Import rules.

    6. Click Import.

      When the import is complete, a banner appears at the top of the page to tell you it was successful.

      To view your documents, click the Documents tab.

    Generate a Command to Import Data

    Import a data set that is larger than 40MB. Generate a custom cbimport command that you can run from the command line. See Command Line Tools to download and install Couchbase Command Line Tools.

    1. Go to Data Tools  Import.

    2. Choose a file to upload or drag-and-drop it into the UI.

    3. Specify the target for your import. You can choose existing Scopes and Collections or create new ones.

    4. Preview and refine your import by:

      1. Choosing how to create document keys

      2. Configuring Import rules

    5. Copy the generated command and replace all values surrounded by brackets. Run the cbimport command from the command line to import your file.

      For more examples of how to use cbimport, see Import and Export Data with Command Line Tools.

    Import Sample Data

    Load sample data to try out Capella’s Data Tools.

    1. Go to Data Tools  Import.

    2. Choose Load sample data.

    3. Choose a sample.

    4. Click Import.

    The Import tool loads data into your cluster. To restore a bucket of data, see Restore a Bucket.