query

package
v3.78.0 Latest Latest
Warning

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

Go to latest
Published: Sep 4, 2024 License: Apache-2.0 Imports: 14 Imported by: 3

Documentation

Overview

Example (ExecuteScript)
ctx := context.TODO()
db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
if err != nil {
	panic(err)
}
defer db.Close(ctx)                      // cleanup resources
op, err := db.Query().ExecuteScript(ctx, // context manage exiting from Do
	`SELECT CAST($id AS Uint64) AS id, CAST($myStr AS Text) AS myStr`,
	time.Hour,
	query.WithParameters(
		ydb.ParamsBuilder().
			Param("$id").Uint64(123).
			Param("$myStr").Text("123").
			Build(),
	),
	query.WithIdempotent(),
)
if err != nil {
	panic(err)
}

for {
	status, err := db.Operation().Get(ctx, op.ID)
	if err != nil {
		panic(err)
	}
	if status.Ready {
		break
	}
	time.Sleep(time.Second)
}

var nextToken string
for {
	result, err := db.Query().FetchScriptResults(ctx, op.ID,
		query.WithResultSetIndex(0),
		query.WithRowsLimit(1000),
		query.WithFetchToken(nextToken),
	)
	if err != nil {
		panic(err)
	}
	nextToken = result.NextToken
	for row, err := range result.ResultSet.Rows(ctx) {
		if err != nil {
			panic(err)
		}
		var (
			id    int64
			myStr string
		)
		err = row.Scan(&id, &myStr)
		if err != nil {
			panic(err)
		}
		fmt.Printf("id=%v, myStr='%s'\n", id, myStr)
	}
	if result.NextToken == "" {
		break
	}
}
Output:

Example (QueryRow)
ctx := context.TODO()
db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
if err != nil {
	panic(err)
}
defer db.Close(ctx) // cleanup resources
var (
	id    int32  // required value
	myStr string // optional value
)
// Do retry operation on errors with best effort
row, err := db.Query().QueryRow(ctx, // context manage exiting from Do
	`SELECT 42 as id, "my string" as myStr`,
	query.WithIdempotent(),
)
if err != nil {
	panic(err)
}

err = row.ScanNamed(
	query.Named("id", &id),
	query.Named("myStr", &myStr),
)
if err != nil {
	panic(err)
}

fmt.Printf("id=%v, myStr='%s'\n", id, myStr)
Output:

Example (QueryWithMaterializedResult)
ctx := context.TODO()
db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
if err != nil {
	panic(err)
}
defer db.Close(ctx) // cleanup resources
var (
	id    int32  // required value
	myStr string // optional value
)
// Do retry operation on errors with best effort
materilizedResult, err := db.Query().Query(ctx, // context manage exiting from Do
	`SELECT 42 as id, "my string" as myStr`,
	query.WithIdempotent(),
)
if err != nil {
	panic(err)
}
defer func() {
	_ = materilizedResult.Close(ctx)
}()

for rs, err := range materilizedResult.ResultSets(ctx) {
	if err != nil {
		panic(err)
	}
	for row, err := range rs.Rows(ctx) {
		if err != nil {
			panic(err)
		}
		err = row.ScanNamed(
			query.Named("id", &id),
			query.Named("myStr", &myStr),
		)
		if err != nil {
			panic(err)
		}
	}
}

fmt.Printf("id=%v, myStr='%s'\n", id, myStr)
Output:

Example (QueryWithMaterializedResultSet)
ctx := context.TODO()
db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
if err != nil {
	panic(err)
}
defer db.Close(ctx) // cleanup resources
var (
	id    int32  // required value
	myStr string // optional value
)
// Do retry operation on errors with best effort
materilizedResultSet, err := db.Query().QueryResultSet(ctx, // context manage exiting from Do
	`SELECT 42 as id, "my string" as myStr`,
	query.WithIdempotent(),
)
if err != nil {
	panic(err)
}

for row, err := range materilizedResultSet.Rows(ctx) {
	if err != nil {
		panic(err)
	}
	err = row.ScanNamed(
		query.Named("id", &id),
		query.Named("myStr", &myStr),
	)
	if err != nil {
		panic(err)
	}
}

fmt.Printf("id=%v, myStr='%s'\n", id, myStr)
Output:

Example (RertryWithTx)
ctx := context.TODO()
db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
if err != nil {
	fmt.Printf("failed connect: %v", err)

	return
}
defer db.Close(ctx) // cleanup resources
var (
	id    int32  // required value
	myStr string // optional value
)
// Do retry operation on errors with best effort
err = db.Query().DoTx(ctx, // context manage exiting from Do
	func(ctx context.Context, tx query.TxActor) (err error) { // retry operation
		res, err := tx.Query(ctx,
			`SELECT 42 as id, "my string" as myStr`,
		)
		if err != nil {
			return err // for auto-retry with driver
		}
		defer func() { _ = res.Close(ctx) }() // cleanup resources
		// for loop with ResultSets available with Go version 1.23+
		for rs, err := range res.ResultSets(ctx) {
			if err != nil {
				return err
			}
			// for loop with ResultSets available with Go version 1.23+
			for row, err := range rs.Rows(ctx) {
				if err != nil {
					return err
				}
				if err = row.ScanNamed(
					query.Named("id", &id),
					query.Named("myStr", &myStr),
				); err != nil {
					return err // generally scan error not retryable, return it for driver check error
				}
			}
		}

		return nil
	},
	query.WithIdempotent(),
	query.WithTxSettings(query.TxSettings(
		query.WithSnapshotReadOnly(),
	)),
)
if err != nil {
	fmt.Printf("unexpected error: %v", err)
}
fmt.Printf("id=%v, myStr='%s'\n", id, myStr)
Output:

Example (ResultStats)
ctx := context.TODO()
db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
if err != nil {
	panic(err)
}
defer db.Close(ctx) // cleanup resources
var (
	id    int32  // required value
	myStr string // required value
)
var stats query.Stats
// Do retry operation on errors with best effort
row, err := db.Query().QueryRow(ctx, // context manage exiting from Do
	`SELECT CAST($id AS Uint64) AS id, CAST($myStr AS Text) AS myStr`,
	query.WithParameters(
		ydb.ParamsBuilder().
			Param("$id").Uint64(123).
			Param("$myStr").Text("123").
			Build(),
	),
	query.WithStatsMode(query.StatsModeFull, func(s query.Stats) {
		stats = s
	}),
	query.WithIdempotent(),
)
if err != nil {
	panic(err)
}

err = row.ScanNamed(
	query.Named("id", &id),
	query.Named("myStr", &myStr),
)
if err != nil {
	panic(err)
}

fmt.Printf("id=%v, myStr='%s'\n", id, myStr)
fmt.Println("Stats:")
fmt.Printf("- Compilation='%v'\n", stats.Compilation())
fmt.Printf("- TotalCPUTime='%v'\n", stats.TotalCPUTime())
fmt.Printf("- ProcessCPUTime='%v'\n", stats.ProcessCPUTime())
fmt.Printf("- QueryAST='%v'\n", stats.QueryAST())
fmt.Printf("- QueryPlan='%v'\n", stats.QueryPlan())
fmt.Println("- Phases:")
for {
	phase, ok := stats.NextPhase()
	if !ok {
		break
	}
	fmt.Printf("  - CPUTime='%v'\n", phase.CPUTime())
	fmt.Printf("  - Duration='%v'\n", phase.Duration())
	fmt.Printf("  - IsLiteralPhase='%v'\n", phase.IsLiteralPhase())
	fmt.Printf("  - AffectedShards='%v'\n", phase.AffectedShards())
	fmt.Println("  - TableAccesses:")
	for {
		tableAccess, ok := phase.NextTableAccess()
		if !ok {
			break
		}
		fmt.Printf("    - %v\n", tableAccess)
	}
}
Output:

Example (RetryWithSessions)
ctx := context.TODO()
db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
if err != nil {
	panic(err)
}
defer db.Close(ctx) // cleanup resources
var (
	id    int32  // required value
	myStr string // required value
)
// Do retry operation on errors with best effort
err = db.Query().Do(ctx, func(ctx context.Context, s query.Session) error {
	streamResult, err := s.Query(ctx, // context manage exiting from Do
		`SELECT CAST($id AS Uint64) AS id, CAST($myStr AS Text) AS myStr`,
		query.WithParameters(
			ydb.ParamsBuilder().
				Param("$id").Uint64(123).
				Param("$myStr").Text("123").
				Build(),
		),
	)
	if err != nil {
		panic(err)
	}
	defer func() {
		_ = streamResult.Close(ctx)
	}()

	for rs, err := range streamResult.ResultSets(ctx) {
		if err != nil {
			return err
		}
		for row, err := range rs.Rows(ctx) {
			if err != nil {
				return err
			}
			err = row.ScanNamed(
				query.Named("id", &id),
				query.Named("myStr", &myStr),
			)
			if err != nil {
				panic(err)
			}
		}
	}

	return nil
}, query.WithIdempotent())
if err != nil {
	panic(err)
}

fmt.Printf("id=%v, myStr='%s'\n", id, myStr)
Output:

Example (SelectWithParameters)
ctx := context.TODO()
db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
if err != nil {
	panic(err)
}
defer db.Close(ctx) // cleanup resources
var (
	id    int32  // required value
	myStr string // required value
)
// Do retry operation on errors with best effort
row, err := db.Query().QueryRow(ctx, // context manage exiting from Do
	`SELECT CAST($id AS Uint64) AS id, CAST($myStr AS Text) AS myStr`,
	query.WithParameters(
		ydb.ParamsBuilder().
			Param("$id").Uint64(123).
			Param("$myStr").Text("123").
			Build(),
	),
	query.WithIdempotent(),
)
if err != nil {
	panic(err)
}

err = row.ScanNamed(
	query.Named("id", &id),
	query.Named("myStr", &myStr),
)
if err != nil {
	panic(err)
}

fmt.Printf("id=%v, myStr='%s'\n", id, myStr)
Output:

Example (WithoutRangeIterators)
ctx := context.TODO()
db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
if err != nil {
	panic(err)
}
defer db.Close(ctx) // cleanup resources
var (
	id    int32  // required value
	myStr string // optional value
)
materializedResult, err := db.Query().Query(ctx, `SELECT 42 as id, "my string" as myStr`,
	query.WithIdempotent(),
)
if err != nil {
	panic(err)
}
for {
	rs, err := materializedResult.NextResultSet(ctx)
	if err != nil {
		if errors.Is(err, io.EOF) {
			break
		}
		panic(err)
	}
	for {
		row, err := rs.NextRow(ctx)
		if err != nil {
			if errors.Is(err, io.EOF) {
				break
			}
			panic(err)
		}
		err = row.ScanNamed(
			query.Named("id", &id),
			query.Named("myStr", &myStr),
		)
		if err != nil {
			panic(err)
		}

		fmt.Printf("id=%v, myStr='%s'\n", id, myStr)
	}
}
Output:

Index

Examples

Constants

View Source
const (
	SyntaxYQL        = options.SyntaxYQL
	SyntaxPostgreSQL = options.SyntaxPostgreSQL
)
View Source
const (
	ExecModeParse    = options.ExecModeParse
	ExecModeValidate = options.ExecModeValidate
	ExecModeExplain  = options.ExecModeExplain
	ExecModeExecute  = options.ExecModeExecute
)
View Source
const (
	StatsModeBasic   = options.StatsModeBasic
	StatsModeNone    = options.StatsModeNone
	StatsModeFull    = options.StatsModeFull
	StatsModeProfile = options.StatsModeProfile
)

Variables

This section is empty.

Functions

func BeginTx

func BeginTx(opts ...TransactionOption) internal.ControlOption

BeginTx returns selector transaction control option

func CommitTx

func CommitTx() internal.ControlOption

CommitTx returns commit transaction control option

func WithCallOptions

func WithCallOptions(opts ...grpc.CallOption) options.Execute

func WithCommit

func WithCommit() options.Execute

func WithExecMode

func WithExecMode(mode options.ExecMode) options.Execute

func WithFetchToken added in v3.77.0

func WithFetchToken(fetchToken string) options.FetchScriptOption

func WithIdempotent

func WithIdempotent() options.RetryOptionsOption

func WithInconsistentReads

func WithInconsistentReads() internal.OnlineReadOnlyOption

func WithLabel added in v3.57.1

func WithLabel(lbl string) options.RetryOptionsOption

func WithParameters

func WithParameters(parameters *params.Parameters) options.Execute

func WithResultSetIndex added in v3.77.0

func WithResultSetIndex(resultSetIndex int64) options.FetchScriptOption

func WithRetryBudget added in v3.66.0

func WithRetryBudget(b budget.Budget) options.RetryOptionsOption

WithRetryBudget creates option with external budget

Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental

func WithRowsLimit added in v3.77.0

func WithRowsLimit(rowsLimit int64) options.FetchScriptOption

func WithStatsMode

func WithStatsMode(mode options.StatsMode, callback func(Stats)) options.Execute

func WithSyntax

func WithSyntax(syntax options.Syntax) options.Execute

func WithTrace

func WithTrace(t *trace.Query) options.TraceOption

func WithTxControl

func WithTxControl(txControl *tx.Control) options.Execute

func WithTxID

func WithTxID(txID string) internal.ControlOption

func WithTxSettings

func WithTxSettings(txSettings tx.Settings) options.DoTxOption

Types

type Client

type Client interface {
	Executor

	// Do provide the best effort for execute operation.
	//
	// Do implements internal busy loop until one of the following conditions is met:
	// - deadline was canceled or deadlined
	// - retry operation returned nil as error
	//
	// Warning: if context without deadline or cancellation func than Do can run indefinitely.
	Do(ctx context.Context, op Operation, opts ...DoOption) error

	// DoTx provide the best effort for execute transaction.
	//
	// DoTx implements internal busy loop until one of the following conditions is met:
	// - deadline was canceled or deadlined
	// - retry operation returned nil as error
	//
	// DoTx makes auto selector (with TransactionSettings, by default - SerializableReadWrite), commit and
	// rollback (on error) of transaction.
	//
	// If op TxOperation returns nil - transaction will be committed
	// If op TxOperation return non nil - transaction will be rollback
	// Warning: if context without deadline or cancellation func than DoTx can run indefinitely
	DoTx(ctx context.Context, op TxOperation, opts ...DoTxOption) error

	// Exec execute query without result
	//
	// Exec used by default:
	// - DefaultTxControl
	Exec(ctx context.Context, query string, opts ...options.Execute) error

	// Query execute query with materialized result
	//
	// Warning: the large result from query will be materialized and can happened to "OOM killed" problem
	//
	// Exec used by default:
	// - DefaultTxControl
	Query(ctx context.Context, query string, opts ...options.Execute) (Result, error)

	// QueryResultSet is a helper which read all rows from first result set in result
	//
	// Warning: the large result set from query will be materialized and can happened to "OOM killed" problem
	//
	// Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental
	QueryResultSet(ctx context.Context, query string, opts ...options.Execute) (ClosableResultSet, error)

	// QueryRow is a helper which read only one row from first result set in result
	//
	// ReadRow returns error if result contains more than one result set or more than one row
	//
	// Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental
	QueryRow(ctx context.Context, query string, opts ...options.Execute) (Row, error)

	// ExecuteScript starts long executing script with polling results later
	//
	// Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental
	ExecuteScript(
		ctx context.Context, query string, ttl time.Duration, ops ...options.Execute,
	) (*options.ExecuteScriptOperation, error)

	// FetchScriptResults fetching the script results
	//
	// Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental
	FetchScriptResults(
		ctx context.Context, opID string, opts ...options.FetchScriptOption,
	) (*options.FetchScriptResult, error)
}

Client defines API of query client

Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental

type ClosableResultSet added in v3.78.0

type ClosableResultSet = result.ClosableResultSet

type ClosableSession

type ClosableSession interface {
	closer.Closer

	Session
}

type DoOption

type DoOption = options.DoOption

type DoTxOption

type DoTxOption = options.DoTxOption

type Executor added in v3.77.0

type Executor interface {
	// Exec execute query without result
	//
	// Exec used by default:
	// - DefaultTxControl
	Exec(ctx context.Context, query string, opts ...options.Execute) error

	// Query execute query with result
	//
	// Exec used by default:
	// - DefaultTxControl
	Query(ctx context.Context, query string, opts ...options.Execute) (Result, error)

	// QueryResultSet execute query and take the exactly single materialized result set from result
	//
	// Exec used by default:
	// - DefaultTxControl
	QueryResultSet(ctx context.Context, query string, opts ...options.Execute) (ClosableResultSet, error)

	// QueryRow execute query and take the exactly single row from exactly single result set from result
	//
	// Exec used by default:
	// - DefaultTxControl
	QueryRow(ctx context.Context, query string, opts ...options.Execute) (Row, error)
}

Executor is an interface for execute queries

Experimental: https://github.com/ydb-platform/ydb-go-sdk/blob/master/VERSIONING.md#experimental

type NamedDestination added in v3.73.0

type NamedDestination = scanner.NamedDestination

func Named

func Named(columnName string, destinationValueReference interface{}) (dst NamedDestination)

type Operation

type Operation func(ctx context.Context, s Session) error

Operation is the interface that holds an operation for retry. if Operation returns not nil - operation will retry if Operation returns nil - retry loop will break

type Result

type Result = result.Result

type ResultSet

type ResultSet = result.Set

type Row

type Row = result.Row

type ScanStructOption added in v3.73.0

type ScanStructOption = scanner.ScanStructOption

func WithScanStructAllowMissingColumnsFromSelect

func WithScanStructAllowMissingColumnsFromSelect() ScanStructOption

func WithScanStructAllowMissingFieldsInStruct

func WithScanStructAllowMissingFieldsInStruct() ScanStructOption

func WithScanStructTagName

func WithScanStructTagName(name string) ScanStructOption

type Session

type Session interface {
	SessionInfo
	Executor

	Begin(ctx context.Context, txSettings TransactionSettings) (Transaction, error)
}

type SessionInfo

type SessionInfo interface {
	ID() string
	NodeID() uint32
	Status() string
}

type Stats added in v3.59.0

type Stats = stats.QueryStats

type Transaction

type Transaction interface {
	TxActor

	CommitTx(ctx context.Context) (err error)
	Rollback(ctx context.Context) (err error)
}

type TransactionControl

type TransactionControl = internal.Control

func DefaultTxControl

func DefaultTxControl() *TransactionControl

DefaultTxControl returns default transaction control for use default tx control on server-side

func NoTx

func NoTx() *TransactionControl

func OnlineReadOnlyTxControl

func OnlineReadOnlyTxControl(opts ...internal.OnlineReadOnlyOption) *TransactionControl

OnlineReadOnlyTxControl returns online read-only transaction control

func SerializableReadWriteTxControl

func SerializableReadWriteTxControl(opts ...internal.ControlOption) *TransactionControl

SerializableReadWriteTxControl returns transaction control with serializable read-write isolation mode

func SnapshotReadOnlyTxControl

func SnapshotReadOnlyTxControl() *TransactionControl

SnapshotReadOnlyTxControl returns snapshot read-only transaction control

func StaleReadOnlyTxControl

func StaleReadOnlyTxControl() *TransactionControl

StaleReadOnlyTxControl returns stale read-only transaction control

func TxControl

func TxControl(opts ...internal.ControlOption) *TransactionControl

TxControl makes transaction control from given options

type TransactionOption added in v3.74.0

type TransactionOption = internal.Option

func WithDefaultTxMode

func WithDefaultTxMode() TransactionOption

func WithOnlineReadOnly

func WithOnlineReadOnly(opts ...internal.OnlineReadOnlyOption) TransactionOption

func WithSerializableReadWrite

func WithSerializableReadWrite() TransactionOption

func WithSnapshotReadOnly

func WithSnapshotReadOnly() TransactionOption

func WithStaleReadOnly

func WithStaleReadOnly() TransactionOption

type TransactionSettings

type TransactionSettings = internal.Settings

func TxSettings

func TxSettings(opts ...internal.Option) TransactionSettings

TxSettings returns transaction settings

type TxActor

type TxActor interface {
	tx.Identifier
	Executor
}

type TxOperation

type TxOperation func(ctx context.Context, tx TxActor) error

TxOperation is the interface that holds an operation for retry. if TxOperation returns not nil - operation will retry if TxOperation returns nil - retry loop will break

type Type added in v3.73.0

type Type = types.Type

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL