writer

package
v0.4.0-alpha.1 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. WithSQLInsertKind selects the INSERT statement prefix. INSERT OR IGNORE and INSERT OR UPDATE are valid Spanner GoogleSQL DML forms; see the INSERT section in https://cloud.google.com/spanner/docs/reference/standard-sql/dml-syntax . Constructors accept 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 constructors

NewDelimitedWriterWithOptions, NewJSONLWriterWithOptions, and NewSQLInsertWriterWithOptions forward to the primary constructors above.

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")
)

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.

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.

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 DelimitedOption added in v0.3.2 

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

DelimitedOption configures a DelimitedWriter created by NewDelimitedWriter or NewCSVWriter.

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
	// 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, opts ...DelimitedOption) *DelimitedWriter

NewCSVWriter returns a comma-delimited CSV writer configured by options. It is a thin helper for NewDelimitedWriter(out, Comma, opts...).

func NewDelimitedWriter added in v0.3.1 

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

NewDelimitedWriter 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. Delimiter must be non-zero and a valid encoding/csv delimiter.

func NewDelimitedWriterWithOptions deprecated added in v0.3.2 

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

NewDelimitedWriterWithOptions forwards to NewDelimitedWriter.

Deprecated: Use NewDelimitedWriter instead.

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 NewJSONLWriter.

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, options ...JSONLOption) *JSONLWriter

NewJSONLWriter returns a JSONL writer configured by options.

func NewJSONLWriterWithOptions deprecated added in v0.3.2 

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

NewJSONLWriterWithOptions forwards to NewJSONLWriter.

Deprecated: Use NewJSONLWriter instead.

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 writer 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 SQLInsertKind added in v0.4.0 

type SQLInsertKind int

SQLInsertKind selects the INSERT statement prefix written by SQLInsertWriter.

Variants follow Spanner GoogleSQL DML: INSERT OR IGNORE skips rows whose primary key already exists; INSERT OR UPDATE inserts or updates by primary key. They cannot be combined with ON CONFLICT in the same statement, and INSERT is not supported in Partitioned DML. See https://cloud.google.com/spanner/docs/reference/standard-sql/dml-syntax . 

const (
	// SQLInsert writes plain INSERT INTO statements.
	SQLInsert SQLInsertKind = iota
	// SQLInsertOrIgnore writes INSERT OR IGNORE INTO statements.
	SQLInsertOrIgnore
	// SQLInsertOrUpdate writes INSERT OR UPDATE INTO statements.
	SQLInsertOrUpdate
)

func (SQLInsertKind) String added in v0.4.0 

func (k SQLInsertKind) String() string

type SQLInsertOption added in v0.3.2 

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

SQLInsertOption configures a SQLInsertWriter created by NewSQLInsertWriter.

func WithSQLInsertKind added in v0.4.0 

func WithSQLInsertKind(kind SQLInsertKind) SQLInsertOption

WithSQLInsertKind sets the INSERT statement variant for a SQLInsertWriter.

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, options ...SQLInsertOption) *SQLInsertWriter

NewSQLInsertWriter returns a SQL INSERT writer configured by options.

func NewSQLInsertWriterWithOptions deprecated added in v0.3.2 

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

NewSQLInsertWriterWithOptions forwards to NewSQLInsertWriter.

Deprecated: Use NewSQLInsertWriter instead.

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.