convex data

List tables and print data from your database

The convex data command allows you to inspect your Convex deployment’s database directly from the command line.

Usage

npx convex data [table] [options]

Arguments

table · string

If specified, list documents in this table. If omitted, lists all tables in the database.

Options

--limit · number · default: 100

List only the n most recently created documents.

Must be a positive integer.

--order · string · default: "desc"

Order the documents by their _creationTime.

Choices: asc, desc

• asc - Oldest documents first
• desc - Newest documents first

--component · string

Path to the component in the component tree defined in convex.config.ts.

Components are a beta feature.

--format · string

Format to print the data in.

Choices: jsonArray, json, jsonLines, jsonl, pretty

• jsonArray (or json) - Print the data as a JSON array of objects
• jsonLines (or jsonl) - Print the data as a JSON object per line
• pretty - Print the data in a human-readable format (default for terminal output)

Examples

List all tables

List all tables in your deployment:

npx convex data

Output:

messages
users
posts
comments

List documents in a table

View the most recent documents in the users table:

npx convex data users

Limit results

Show only the 10 most recent documents:

npx convex data messages --limit 10

Show oldest documents

List documents in ascending order by creation time:

npx convex data posts --order asc --limit 5

Export as JSON

Output data in JSON format for processing:

npx convex data users --format json > users.json

Export as JSON Lines

Output data as JSON Lines for streaming or line-by-line processing:

npx convex data messages --format jsonLines

Query production data

List tables in your production deployment:

npx convex data --prod

Query component data

List documents from a table in a component:

npx convex data events --component auth/sessions

Output formats

Pretty format (default)

Human-readable table format:

┌────────────────┬──────────┬─────────────────────┐
│ _id            │ name     │ email               │
├────────────────┼──────────┼─────────────────────┤
│ j7896d5k3l2m1n │ Alice    │ [e-mail]   │
│ k8907e6l4m3n2o │ Bob      │ [e-mail]     │
└────────────────┴──────────┴─────────────────────┘

JSON Array format

[
  {
    "_id": "j7896d5k3l2m1n",
    "_creationTime": 1678901234567,
    "name": "Alice",
    "email": "[e-mail]"
  },
  {
    "_id": "k8907e6l4m3n2o",
    "_creationTime": 1678901234890,
    "name": "Bob",
    "email": "[e-mail]"
  }
]

JSON Lines format

{"_id":"j7896d5k3l2m1n","_creationTime":1678901234567,"name":"Alice","email":"[e-mail]"}
{"_id":"k8907e6l4m3n2o","_creationTime":1678901234890,"name":"Bob","email":"[e-mail]"}

Deployment selection

The convex data command supports deployment selection:

• --prod - Target production deployment
• --preview-name <name> - Target a preview deployment
• --url <url> - Target a specific deployment URL
• --admin-key <key> - Admin key for authentication

By default, the command targets your dev deployment.

System fields

All documents include these system fields:

• _id - Unique document identifier
• _creationTime - Timestamp when the document was created (milliseconds since epoch)

Use cases

Debugging

Quickly inspect data during development:

npx convex data users --limit 5

Data export

Export data for analysis or backup:

npx convex data messages --format json --limit 1000 > messages.json

Schema verification

Check what tables exist in your deployment:

npx convex data

Production monitoring

Quickly check recent data in production:

npx convex data errors --prod --limit 10 --order desc

Limitations

• Maximum limit is bounded by deployment limits
• Large datasets should use the export command instead
• Does not support filtering beyond creation time ordering
• For complex queries, use convex run to execute custom query functions