Export Manager

ExportManager

Pandas-style export manager for synchronous operations.

Provides to_csv() and to_jsonl() methods for exporting query results to files or external stages.

class matrixone.export.ExportManager(client: Any)[source]

Bases: object

Manager class for data export operations (pandas-style interface).

This class provides pandas-like methods to export query results to local files or external stages.

Examples:

# CSV export (pandas-style)
client.export.to_csv('data.csv', query, sep='|', header=True)

# JSONL export
client.export.to_jsonl('data.jsonl', query)

# Export to S3 stage
client.export.to_csv('stage://s3_stage/data.csv', query)
__init__(client: Any)[source]

Initialize ExportManager with a client instance.

Parameters:

client – MatrixOne client instance (Client or Session)

to_csv(path: str, query: str | Any, *, sep: str = ',', quotechar: str | None = None, lineterminator: str = '\n', header: bool = False, **kwargs) → Any[source]

Export query results to CSV file (pandas-style).

This method exports query results to a CSV file on the MatrixOne server’s filesystem or to an external stage.

Parameters:

  • path – Output file path. Can be: - Local path: ‘/tmp/data.csv’ - Stage path: ‘stage://stage_name/data.csv’

  • query – SELECT query to execute. Can be: - Raw SQL string: “SELECT * FROM users” - SQLAlchemy select(): select(User).where(User.age > 25) - MatrixOneQuery: client.query(User).filter(User.age > 25)

  • sep – Field separator/delimiter (default: ‘,’)

  • quotechar – Character to quote fields containing special characters

  • lineterminator – Line terminator (default: ‘n’)

  • header – Include column headers (not yet supported by MatrixOne)

  • **kwargs – Reserved for future options

Returns:

Query execution result

Raises:

Examples:

# Basic CSV export with defaults
client.export.to_csv('/tmp/users.csv', "SELECT * FROM users")

# Custom separator (TSV)
client.export.to_csv('/tmp/users.tsv', query, sep='\t')

# With SQLAlchemy
from sqlalchemy import select
stmt = select(User).where(User.age > 25)
client.export.to_csv('/tmp/adults.csv', stmt, sep='|')

# Export to stage
client.export.to_csv('stage://s3_stage/backup.csv', query)

# With MatrixOne query builder
query = client.query(Order).filter(Order.status == 'completed')
client.export.to_csv('/tmp/orders.csv', query, sep=',')

# Using session
with client.session() as session:
    query = session.query(User).filter(User.active == True)
    session.export.to_csv('/tmp/active_users.csv', query)

Note

  • For local paths, the MatrixOne server must have write permissions

  • For stage paths, use format: ‘stage://stage_name/filename.csv’

  • MatrixOne doesn’t support using sep and quotechar simultaneously

  • header=True is not yet supported by MatrixOne

to_jsonl(path: str, query: str | Any, **kwargs) → Any[source]

Export query results to JSONL file (JSON Lines format).

Each line in the output file is a valid JSON object representing one row.

Parameters:

  • path – Output file path. Can be: - Local path: ‘/tmp/data.jsonl’ - Stage path: ‘stage://stage_name/data.jsonl’

  • query – SELECT query to execute (str, SQLAlchemy select(), or MatrixOneQuery)

  • **kwargs – Reserved for future options

Returns:

Query execution result

Examples:

# Basic JSONL export
client.export.to_jsonl('/tmp/users.jsonl', "SELECT * FROM users")

# With SQLAlchemy
from sqlalchemy import select
stmt = select(User).where(User.verified == True)
client.export.to_jsonl('/tmp/verified.jsonl', stmt)

# Export to stage
client.export.to_jsonl('stage://s3_stage/data.jsonl', query)

# Complex query with joins
query = '''
    SELECT u.name, o.total
    FROM users u
    JOIN orders o ON u.id = o.user_id
'''
client.export.to_jsonl('/tmp/user_orders.jsonl', query)

Note

  • JSONL format: one JSON object per line, no array wrapper

  • Each line is a complete, valid JSON object

  • Suitable for streaming and big data processing

to_csv_stage(stage_name: str, filename: str, query: str | Any, *, sep: str = ',', quotechar: str | None = None, lineterminator: str = '\n', header: bool = False, **kwargs) → Any[source]

Export query results to CSV file in an external stage.

This is a convenience method for stage exports that doesn’t require the ‘stage://’ protocol prefix.

Parameters:

  • stage_name – Name of the external stage

  • filename – Name of the file to create in the stage

  • query – SELECT query to execute (str, SQLAlchemy select(), or MatrixOneQuery)

  • sep – Field separator/delimiter (default: ‘,’)

  • quotechar – Character to quote fields containing special characters

  • lineterminator – Line terminator (default: ‘n’)

  • header – Include column headers (not yet supported by MatrixOne)

  • **kwargs – Reserved for future options

Returns:

Query execution result

Examples:

# Export to S3 stage
client.export.to_csv_stage('s3_stage', 'data.csv', "SELECT * FROM users")

# With custom separator
client.export.to_csv_stage('backup_stage', 'data.tsv', query, sep=' ')

# With SQLAlchemy
from sqlalchemy import select
stmt = select(User).where(User.active == True)
client.export.to_csv_stage('active_stage', 'active_users.csv', stmt)

Note

  • The stage must exist before calling this method

  • Use client.stage.create_s3() or client.stage.create_local() to create stages

  • MatrixOne doesn’t support using sep and quotechar simultaneously

to_jsonl_stage(stage_name: str, filename: str, query: str | Any, **kwargs) → Any[source]

Export query results to JSONL file in an external stage.

This is a convenience method for stage exports that doesn’t require the ‘stage://’ protocol prefix.

Parameters:

  • stage_name – Name of the external stage

  • filename – Name of the file to create in the stage

  • query – SELECT query to execute (str, SQLAlchemy select(), or MatrixOneQuery)

  • **kwargs – Reserved for future options

Returns:

Query execution result

Examples:

# Export to S3 stage
client.export.to_jsonl_stage('s3_stage', 'data.jsonl', "SELECT * FROM users")

# With SQLAlchemy
from sqlalchemy import select
stmt = select(User).where(User.verified == True)
client.export.to_jsonl_stage('verified_stage', 'verified.jsonl', stmt)

Note

  • The stage must exist before calling this method

  • Use client.stage.create_s3() or client.stage.create_local() to create stages

AsyncExportManager

Pandas-style export manager for asynchronous operations.

Provides async to_csv() and to_jsonl() methods for non-blocking export operations.

class matrixone.export.AsyncExportManager(client: Any)[source]

Bases: object

Async manager class for data export operations (pandas-style interface).

Provides async versions of all export methods from ExportManager.

Examples:

# Async CSV export
await client.export.to_csv('data.csv', query, sep='|')

# Async JSONL export
await client.export.to_jsonl('data.jsonl', query)
__init__(client: Any)[source]

Initialize AsyncExportManager with an async client instance.

Parameters:

client – MatrixOne async client instance (AsyncClient or AsyncSession)

async to_csv(path: str, query: str | Any, *, sep: str = ',', quotechar: str | None = None, lineterminator: str = '\n', header: bool = False, **kwargs) → Any[source]

Async export query results to CSV file.

See ExportManager.to_csv() for detailed documentation.

Examples:

# Async CSV export
await client.export.to_csv('/tmp/users.csv', "SELECT * FROM users")

# With custom options
await client.export.to_csv(
    '/tmp/data.tsv',
    query,
    sep='\t',
    lineterminator='\r\n'
)

# Using async session
async with client.session() as session:
    query = session.query(User).filter(User.active == True)
    await session.export.to_csv('/tmp/active.csv', query)
async to_jsonl(path: str, query: str | Any, **kwargs) → Any[source]

Async export query results to JSONL file.

See ExportManager.to_jsonl() for detailed documentation.

Examples:

# Async JSONL export
await client.export.to_jsonl('/tmp/data.jsonl', query)

# Export to stage
await client.export.to_jsonl('stage://s3/backup.jsonl', query)
async to_csv_stage(stage_name: str, filename: str, query: str | Any, *, sep: str = ',', quotechar: str | None = None, lineterminator: str = '\n', header: bool = False, **kwargs) → Any[source]

Async export query results to CSV file in an external stage.

This is a convenience method for stage exports that doesn’t require the ‘stage://’ protocol prefix.

Parameters:

  • stage_name – Name of the external stage

  • filename – Name of the file to create in the stage

  • query – SELECT query to execute (str, SQLAlchemy select(), or MatrixOneQuery)

  • sep – Field separator/delimiter (default: ‘,’)

  • quotechar – Character to quote fields containing special characters

  • lineterminator – Line terminator (default: ‘n’)

  • header – Include column headers (not yet supported by MatrixOne)

  • **kwargs – Reserved for future options

Returns:

Query execution result

Examples:

# Async export to S3 stage
await client.export.to_csv_stage('s3_stage', 'data.csv', "SELECT * FROM users")

# With custom separator
await client.export.to_csv_stage('backup_stage', 'data.tsv', query, sep='   ')

# With SQLAlchemy
from sqlalchemy import select
stmt = select(User).where(User.active == True)
await client.export.to_csv_stage('active_stage', 'active_users.csv', stmt)
async to_jsonl_stage(stage_name: str, filename: str, query: str | Any, **kwargs) → Any[source]

Async export query results to JSONL file in an external stage.

This is a convenience method for stage exports that doesn’t require the ‘stage://’ protocol prefix.

Parameters:

  • stage_name – Name of the external stage

  • filename – Name of the file to create in the stage

  • query – SELECT query to execute (str, SQLAlchemy select(), or MatrixOneQuery)

  • **kwargs – Reserved for future options

Returns:

Query execution result

Examples:

# Async export to S3 stage
await client.export.to_jsonl_stage('s3_stage', 'data.jsonl', "SELECT * FROM users")

# With SQLAlchemy
from sqlalchemy import select
stmt = select(User).where(User.verified == True)
await client.export.to_jsonl_stage('verified_stage', 'verified.jsonl', stmt)