writer

package
v0.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 28, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package writer provides small streaming helpers for exporting Spanner rows using spanvalue formatters.

DelimitedWriter is the primary writer for CSV-style delimited text. NewCSVWriter is a thin helper for the common comma-delimited CSV case, while NewDelimitedWriter accepts an explicit delimiter for TSV and other delimited output. DelimitedWriter and JSONLWriter preserve explicit duplicate column names. Their UnnamedFieldNamer only fills empty column names, and generated names avoid collisions with existing names. DelimitedWriter buffers through encoding/csv, so callers must call Flush after the final write.

Use Writer when an adapter only needs row streaming, and FlushWriter when it owns the full write lifecycle. DelimitedWriter, JSONLWriter, and SQLInsertWriter implement FlushWriter. If an adapter exposes a Close method, that Close method should call Flush; Flush does not close the underlying io.Writer.

Primary API

DelimitedWriter, NewDelimitedWriter, NewCSVWriter, JSONLWriter, NewJSONLWriter, SQLInsertWriter, and NewSQLInsertWriter stream rows. NewDelimitedWriterWithOptions, NewJSONLWriterWithOptions, and NewSQLInsertWriterWithOptions accept explicit options such as WithMetadata and WithFormatter. Each writer's Prepare method initializes schema from result-set metadata (for example DelimitedWriter.Prepare). RowData, FormatDelimitedRow, and FormatJSONLRow support one-row paths.

Compatibility API

CSVWriter is a type alias for DelimitedWriter. DelimitedWriter.Comma and a zero delimiter passed to NewDelimitedWriter select comma for compatibility; prefer NewCSVWriter or NewDelimitedWriter with Comma.

Index

Constants

View Source 
const (
	// Comma is the standard CSV field delimiter. Pass Comma to
	// NewDelimitedWriter for CSV output.
	Comma rune = ','
)

Variables

View Source 
var (
	// ErrEmptyTableName reports that SQLInsertWriter.Table is empty.
	ErrEmptyTableName = errors.New("empty table name")
	// ErrEmptyColumnName reports that a SQL writer received an empty column name.
	ErrEmptyColumnName = errors.New("empty column name")
	// ErrNilOutputWriter reports that a writer was constructed without an output.
	ErrNilOutputWriter = errors.New("nil output writer")
	// ErrNilRow reports that WriteRow was called with a nil row.
	ErrNilRow = spanvalue.ErrNilRow
	// ErrMissingColumnNames reports that writing values requires initialized column names.
	ErrMissingColumnNames = errors.New("missing column names")
	// ErrColumnNamesMismatch reports that provided column names differ from initialized schema.
	ErrColumnNamesMismatch = errors.New("column names mismatch")
	// ErrHeaderAfterData reports that DelimitedWriter.WriteHeader was called after data rows were emitted.
	ErrHeaderAfterData = errors.New("header after data")
	// ErrInvalidDelimiter reports that DelimitedWriter received an invalid delimiter.
	ErrInvalidDelimiter = errors.New("invalid delimiter")
	// ErrDelimiterAfterWrite reports that DelimitedWriter delimiter changed after the underlying CSV writer was initialized.
	ErrDelimiterAfterWrite = errors.New("delimiter changed after writer initialization")
)

Functions

func FormatDelimitedRow added in v0.3.2 

func FormatDelimitedRow(fc *spanvalue.FormatConfig, row *spanner.Row, delimiter rune) (string, error)

FormatDelimitedRow formats one row as a CSV-style delimited record without a trailing newline. Pass Comma for CSV output. A zero delimiter is accepted for compatibility and is treated as Comma.

func FormatDelimitedValues added in v0.3.2 

func FormatDelimitedValues(fc *spanvalue.FormatConfig, columnNames []string, values []spanner.GenericColumnValue, delimiter rune) (string, error)

FormatDelimitedValues formats one row represented as column names plus GCV values as a CSV-style delimited record without a trailing newline. Pass Comma for CSV output. A zero delimiter is accepted for compatibility and is treated as Comma.

func FormatJSONLRow added in v0.3.2 

func FormatJSONLRow(fc *spanvalue.FormatConfig, row *spanner.Row, namer spanvalue.UnnamedFieldNamer) (string, error)

FormatJSONLRow formats one row as a JSON object string without a trailing newline. Callers writing JSONL streams should add the newline at the stream boundary.

func FormatJSONLValues added in v0.3.2 

func FormatJSONLValues(fc *spanvalue.FormatConfig, columnNames []string, values []spanner.GenericColumnValue, namer spanvalue.UnnamedFieldNamer) (string, error)

FormatJSONLValues formats one row represented as column names plus GCV values as a JSON object string without a trailing newline. Callers writing JSONL streams should add the newline at the stream boundary.

func RowData added in v0.3.2 

func RowData(row *spanner.Row) ([]string, []spanner.GenericColumnValue, error)

RowData extracts column names and GenericColumnValue cells from row.

Types

type CSVWriter deprecated 

type CSVWriter = DelimitedWriter

CSVWriter is a compatibility alias for DelimitedWriter.

Deprecated: use DelimitedWriter.

type DelimitedOption added in v0.3.2 

type DelimitedOption interface {
	// contains filtered or unexported methods
}

DelimitedOption configures a DelimitedWriter created by NewDelimitedWriterWithOptions.

func WithHeader added in v0.3.2 

func WithHeader(header bool) DelimitedOption

WithHeader sets whether DelimitedWriter writes a header before data rows.

type DelimitedWriter added in v0.3.2 

type DelimitedWriter struct {
	Formatter *spanvalue.FormatConfig
	Header    bool
	// Comma is the field delimiter. The zero value selects Comma for
	// compatibility. Set it before the first write; use '\t' for TSV output.
	// Any non-zero delimiter must be a valid encoding/csv delimiter: a valid
	// rune other than '"', '\r', '\n', or utf8.RuneError.
	//
	// Deprecated: prefer the delimiter argument to NewDelimitedWriter or
	// NewDelimitedWriterWithOptions.
	Comma rune
	// Set before the first write. Once names have been resolved for the current
	// schema, later changes do not retroactively rewrite cached header names.
	UnnamedFieldNamer spanvalue.UnnamedFieldNamer
	// contains filtered or unexported fields
}

DelimitedWriter writes rows as CSV-style delimited text. Call Flush after the final write.

func NewCSVWriter 

func NewCSVWriter(out io.Writer, metadata ...*sppb.ResultSetMetadata) *DelimitedWriter

NewCSVWriter returns a CSV writer optionally initialized from result-set metadata. It is a thin helper for NewDelimitedWriter(out, Comma, metadata...).

func NewDelimitedWriter added in v0.3.1 

func NewDelimitedWriter(out io.Writer, delimiter rune, metadata ...*sppb.ResultSetMetadata) *DelimitedWriter

NewDelimitedWriter returns a CSV-style writer using delimiter as the field delimiter. Pass Comma for CSV output or '\t' for TSV output. A zero delimiter is accepted for compatibility and is treated as Comma.

func NewDelimitedWriterWithOptions added in v0.3.2 

func NewDelimitedWriterWithOptions(out io.Writer, delimiter rune, options ...DelimitedOption) *DelimitedWriter

NewDelimitedWriterWithOptions returns a CSV-style writer using delimiter as the field delimiter and configured by options. Pass Comma for CSV output or '\t' for TSV output. A zero delimiter is accepted for compatibility and is treated as Comma.

func (*DelimitedWriter) Flush added in v0.3.2 

func (w *DelimitedWriter) Flush() error

Flush flushes buffered delimited data to the underlying writer. It does not close the underlying writer.

func (*DelimitedWriter) Prepare added in v0.3.2 

func (w *DelimitedWriter) Prepare(metadata *sppb.ResultSetMetadata) error

Prepare initializes the delimited schema from result-set metadata before the first row is written. If a schema is already initialized, Prepare verifies that the metadata column names match the existing schema.

func (*DelimitedWriter) WriteGCVs added in v0.3.2 

func (w *DelimitedWriter) WriteGCVs(values []spanner.GenericColumnValue) error

func (*DelimitedWriter) WriteHeader added in v0.3.2 

func (w *DelimitedWriter) WriteHeader() error

WriteHeader writes the delimited header once using the initialized column names.

func (*DelimitedWriter) WriteRow added in v0.3.2 

func (w *DelimitedWriter) WriteRow(row *spanner.Row) error

WriteRow writes one delimited row, initializing the schema from row metadata if needed.

func (*DelimitedWriter) WriteValues added in v0.3.2 

func (w *DelimitedWriter) WriteValues(columnNames []string, values []spanner.GenericColumnValue) error

type FlushWriter added in v0.3.2 

type FlushWriter interface {
	Writer
	Flusher
}

FlushWriter streams Spanner rows and finalizes any buffered output.

type Flusher added in v0.3.1 

type Flusher interface {
	Flush() error
}

Flusher finalizes any buffered output. Flush does not close the underlying io.Writer. DelimitedWriter uses Flush to forward buffered CSV-style data; JSONLWriter and SQLInsertWriter implement it as a no-op so adapters can use one finalize path for all writer implementations.

type JSONLOption added in v0.3.2 

type JSONLOption interface {
	// contains filtered or unexported methods
}

JSONLOption configures a JSONLWriter created by NewJSONLWriterWithOptions.

type JSONLWriter 

type JSONLWriter struct {
	Formatter *spanvalue.FormatConfig
	// Set before the first write. Once names have been resolved for the current
	// schema, later changes do not retroactively rewrite cached object keys.
	UnnamedFieldNamer spanvalue.UnnamedFieldNamer
	// contains filtered or unexported fields
}

JSONLWriter writes one JSON object per line.

func NewJSONLWriter 

func NewJSONLWriter(out io.Writer, metadata ...*sppb.ResultSetMetadata) *JSONLWriter

NewJSONLWriter returns a JSONL writer optionally initialized from result-set metadata.

func NewJSONLWriterWithOptions added in v0.3.2 

func NewJSONLWriterWithOptions(out io.Writer, options ...JSONLOption) *JSONLWriter

NewJSONLWriterWithOptions returns a JSONL writer configured by options.

func (*JSONLWriter) Flush added in v0.3.1 

func (w *JSONLWriter) Flush() error

Flush finalizes JSONL output. JSONLWriter is unbuffered, so this is a no-op.

func (*JSONLWriter) Prepare added in v0.3.2 

func (w *JSONLWriter) Prepare(metadata *sppb.ResultSetMetadata) error

Prepare initializes the JSONL schema from result-set metadata before the first row is written. If a schema is already initialized, Prepare verifies that the metadata column names match the existing schema.

func (*JSONLWriter) WriteGCVs 

func (w *JSONLWriter) WriteGCVs(values []spanner.GenericColumnValue) error

func (*JSONLWriter) WriteRow 

func (w *JSONLWriter) WriteRow(row *spanner.Row) error

func (*JSONLWriter) WriteValues 

func (w *JSONLWriter) WriteValues(columnNames []string, values []spanner.GenericColumnValue) error

type NameOption added in v0.3.2 

type NameOption interface {
	DelimitedOption
	JSONLOption
}

NameOption configures field-name handling for delimited and JSONL writers.

func WithUnnamedFieldNamer added in v0.3.2 

func WithUnnamedFieldNamer(namer spanvalue.UnnamedFieldNamer) NameOption

WithUnnamedFieldNamer sets the unnamed-field naming policy for delimited and JSONL writers.

type Option added in v0.3.2 

type Option interface {
	DelimitedOption
	JSONLOption
	SQLInsertOption
}

Option configures any writer type created by a WithOptions constructor.

func WithFormatter added in v0.3.2 

func WithFormatter(formatter *spanvalue.FormatConfig) Option

WithFormatter sets the FormatConfig used by a writer.

func WithMetadata added in v0.3.2 

func WithMetadata(metadata *sppb.ResultSetMetadata) Option

WithMetadata initializes a writer schema from result-set metadata.

type SQLInsertOption added in v0.3.2 

type SQLInsertOption interface {
	// contains filtered or unexported methods
}

SQLInsertOption configures a SQLInsertWriter created by NewSQLInsertWriterWithOptions.

type SQLInsertWriter 

type SQLInsertWriter struct {
	Table     string
	Formatter *spanvalue.FormatConfig
	// contains filtered or unexported fields
}

SQLInsertWriter writes rows as GoogleSQL INSERT statements.

func NewSQLInsertWriter 

func NewSQLInsertWriter(out io.Writer, table string, metadata ...*sppb.ResultSetMetadata) *SQLInsertWriter

NewSQLInsertWriter returns a SQL INSERT writer optionally initialized from result-set metadata.

func NewSQLInsertWriterWithOptions added in v0.3.2 

func NewSQLInsertWriterWithOptions(out io.Writer, table string, options ...SQLInsertOption) *SQLInsertWriter

NewSQLInsertWriterWithOptions returns a SQL INSERT writer configured by options.

func (*SQLInsertWriter) Flush added in v0.3.1 

func (w *SQLInsertWriter) Flush() error

Flush finalizes SQL INSERT output. SQLInsertWriter is unbuffered, so this is a no-op.

func (*SQLInsertWriter) Prepare added in v0.3.2 

func (w *SQLInsertWriter) Prepare(metadata *sppb.ResultSetMetadata) error

Prepare initializes the SQL INSERT schema from result-set metadata before the first row is written. If a schema is already initialized, Prepare verifies that the metadata column names match the existing schema.

func (*SQLInsertWriter) WriteGCVs 

func (w *SQLInsertWriter) WriteGCVs(values []spanner.GenericColumnValue) error

func (*SQLInsertWriter) WriteRow 

func (w *SQLInsertWriter) WriteRow(row *spanner.Row) error

func (*SQLInsertWriter) WriteValues 

func (w *SQLInsertWriter) WriteValues(columnNames []string, values []spanner.GenericColumnValue) error

type Writer 

type Writer interface {
	WriteRow(row *spanner.Row) error
}

Writer writes Spanner rows to an output stream.

Writer intentionally models row streaming only. Some concrete writers also implement Flusher; callers that own the full write lifecycle must call Flush after the final row when it is available. Factories that may return a buffered writer should return a concrete type or FlushWriter, not Writer alone.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.