Working with Apache Cassandra in Docker is extremely common for developers, testers, and DevOps engineers. One question that often comes up is:
“My CSV file is on my local computer, but Cassandra is running inside a Docker container. How do I import it using cqlsh?”
The answer is actually quite simple once you understand how Docker containers access files.
This beginner’s guide explains everything step by step, even if you’ve never worked with Cassandra or Docker before.
Understanding the Problem
Imagine you have:
- A CSV file stored on your computer
C:\Users\John\Downloads\data.csv
or
/home/john/data.csv
Meanwhile, Cassandra is running inside Docker.
When you open cqlsh inside the container, it cannot see files stored on your computer.
Think of a Docker container as a separate mini-computer.
It has:
- its own filesystem
- its own directories
- its own applications
Your computer’s files are not automatically visible inside the container.
Why the COPY Command Doesn’t Work
Many beginners try something like:
COPY my_table FROM 'C:\Users\John\data.csv';
or
COPY my_table FROM '/home/john/data.csv';
inside the container.
It fails because those paths only exist on your host machine—not inside Docker.
Solution 1: Copy the CSV into the Container
The easiest solution is to copy the file into the container first.
Docker provides the command:
docker cp
Example:
docker cp data.csv cassandra:/tmp/data.csv
This copies
Local computer
↓
Docker container
Now the file exists inside the container.
Verify the File
Enter the container:
docker exec -it cassandra bash
or
docker exec -it cassandra sh
Check that the file is there:
ls /tmp
Output might look like:
data.csv
Import the CSV with cqlsh
Start Cassandra’s shell:
cqlsh
Now execute:
COPY my_keyspace.users
(id, name, age)
FROM '/tmp/data.csv'
WITH HEADER = TRUE;
This tells Cassandra:
- read the file
- skip the header row
- insert the remaining records
Running Everything Without Opening a Shell
You can also execute the command directly:
docker exec cassandra \
cqlsh \
-e "COPY my_keyspace.users (id,name,age) FROM '/tmp/data.csv' WITH HEADER = TRUE;"
This is useful in scripts and CI/CD pipelines.
Example Project
Suppose your CSV looks like:
id,name,age
1,Alice,25
2,Bob,31
3,Charlie,40
Your table:
CREATE TABLE users (
id int PRIMARY KEY,
name text,
age int
);
Import command:
COPY users
(id,name,age)
FROM '/tmp/users.csv'
WITH HEADER = TRUE;
After completion:
id | name | age
--------------------
1 | Alice | 25
2 | Bob | 31
3 | Charlie | 40
Alternative: Mount a Local Folder
Instead of copying the file every time, you can mount a local directory when starting Docker.
Example:
docker run \
-v C:\Data:/import \
cassandra
or on Linux:
docker run \
-v /home/john/import:/import \
cassandra
Now anything inside your local folder appears inside the container:
Local
/home/john/import/data.csv
↓
Container
/import/data.csv
Then:
COPY users
FROM '/import/data.csv'
WITH HEADER=TRUE;
This is especially useful during development.
Common Errors
File Not Found
Example:
Cannot open file
Cause:
The file is not inside the container.
Solution:
- use
docker cp - verify with
ls
Wrong Path
Example:
COPY users
FROM 'C:\Users\data.csv'
Inside Linux containers, Windows paths don’t exist.
Use:
/tmp/data.csv
or another valid Linux path.
Permission Denied
Sometimes the file exists but Cassandra cannot read it.
Check permissions:
ls -l /tmp/data.csv
If necessary:
chmod 644 /tmp/data.csv
Column Count Doesn’t Match
Example:
CSV contains more columns than expected
Verify that:
- CSV columns
- COPY statement
- table definition
all match.
Wrong Data Types
Example:
Trying to insert
abc
into an integer column.
Always verify that the CSV format matches the Cassandra schema.
Performance Tips
For larger imports:
- use SSD storage
- avoid running heavy workloads simultaneously
- import during maintenance windows
- split very large CSV files into smaller chunks
- verify the imported row count afterward
Best Practices
✔ Keep CSV files with headers.
✔ Match CSV columns to the table definition.
✔ Validate data before importing.
✔ Test with a small sample first.
✔ Back up important data before large imports.
✔ Verify the imported data after the operation.
When to Use COPY
The COPY command is ideal for:
- Development
- Testing
- Small migrations
- Initial data loading
- Demonstrations
For extremely large datasets, specialized bulk-loading tools may provide better performance.
Quick Command Summary
Copy the CSV into the container:
docker cp data.csv cassandra:/tmp/data.csv
Open the container:
docker exec -it cassandra bash
Start cqlsh:
cqlsh
Import the data:
COPY my_keyspace.users
(id,name,age)
FROM '/tmp/data.csv'
WITH HEADER=TRUE;
Conclusion
Importing a CSV into Cassandra running inside Docker is straightforward once you understand that the container has its own isolated filesystem. The most common approach is to copy the CSV into the container with docker cp and then use the COPY command in cqlsh. For repeated imports during development, mounting a host directory as a Docker volume can save time and simplify the workflow. By verifying file locations, permissions, and schema compatibility before importing, you can avoid the most common errors and ensure a smooth data-loading process.
Frequently Asked Questions (FAQ)
Can cqlsh read files directly from my computer?
No. When cqlsh runs inside a Docker container, it can only access files available inside that container.
What is the easiest way to make the CSV available?
Use:
docker cp
to copy the file into the container.
Can I avoid copying the file every time?
Yes. Mount a local directory into the container using Docker volumes.
Does the CSV need a header?
Not necessarily, but if it has one, use:
WITH HEADER = TRUE
Can I import millions of rows using COPY?
You can, but for very large datasets, specialized bulk-loading tools are generally more efficient.
References
- Apache Cassandra Documentation –
COPYcommand - Apache Cassandra
cqlshUser Guide - Docker Documentation –
docker cp - Docker Documentation – Bind Mounts and Volumes
