Documentation
¶
Overview ¶
Package query provides a simplified API for running queries in BigQuery.
This package is EXPERIMENTAL and subject to change without notice.
The query client provides a simplified interface for running queries and retrieving results. It handles the complexities of job management and result pagination.
Example usage:
ctx := context.Background()
client, err := apiv2_client.NewClient(ctx)
if err != nil {
// TODO: Handle error.
}
defer client.Close()
helper, err := query.NewHelper(client, "my-project")
if err != nil {
// TODO: Handle error.
}
req := helper.FromSQL("SELECT 1 as foo")
q, err := helper.StartQuery(ctx, req)
if err != nil {
// TODO: Handle error.
}
if err := q.Wait(ctx); err != nil {
// TODO: Handle error.
}
it, err := q.Read(ctx)
if err != nil {
// TODO: Handle error.
}
// TODO: iterate results.
Index ¶
- type Helper
- func (h *Helper) AttachJob(ctx context.Context, jobRef *bigquerypb.JobReference, opts ...gax.CallOption) (*Query, error)
- func (h *Helper) FromSQL(sql string) *bigquerypb.PostQueryRequest
- func (h *Helper) StartQuery(ctx context.Context, req *bigquerypb.PostQueryRequest, opts ...gax.CallOption) (*Query, error)
- func (h *Helper) StartQueryJob(ctx context.Context, job *bigquerypb.Job, opts ...gax.CallOption) (*Query, error)
- type Query
- func (q *Query) Complete() bool
- func (q *Query) Done(opts ...gax.CallOption) <-chan struct{}
- func (q *Query) Err() error
- func (q *Query) JobReference() *bigquerypb.JobReference
- func (q *Query) QueryID() string
- func (q *Query) Read(ctx context.Context, opts ...ReadOption) (*RowIterator, error)
- func (q *Query) Schema() *bigquerypb.TableSchema
- func (q *Query) Wait(ctx context.Context) error
- type ReadOption
- type Row
- type RowIterator
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Helper ¶
type Helper struct {
// contains filtered or unexported fields
}
Helper for running queries in BigQuery. It is a lightweight wrapper around the auto-generated BigQuery v2 client, focused on query operations.
func NewHelper ¶
func NewHelper(c *apiv2_client.Client, projectID string, opts ...option.ClientOption) (*Helper, error)
NewHelper creates a new query helper. This helper should be reused instead of created per-request.
func (*Helper) AttachJob ¶
func (h *Helper) AttachJob(ctx context.Context, jobRef *bigquerypb.JobReference, opts ...gax.CallOption) (*Query, error)
AttachJob attaches to an existing query job. The returned Query object can be used to monitor the job's status, wait for its completion, and retrieve its results.
func (*Helper) FromSQL ¶
func (h *Helper) FromSQL(sql string) *bigquerypb.PostQueryRequest
FromSQL creates a query configuration from a SQL string.
func (*Helper) StartQuery ¶
func (h *Helper) StartQuery(ctx context.Context, req *bigquerypb.PostQueryRequest, opts ...gax.CallOption) (*Query, error)
StartQuery executes a query using the stateless jobs.query RPC. It returns a handle to the running query. The returned Query object can be used to wait for completion and retrieve results.
func (*Helper) StartQueryJob ¶
func (h *Helper) StartQueryJob(ctx context.Context, job *bigquerypb.Job, opts ...gax.CallOption) (*Query, error)
StartQueryJob from a bigquerypb.Job definition. Should have job.Configuration.Query filled out.
type Query ¶
type Query struct {
// contains filtered or unexported fields
}
Query represents a handle to a query job. Its methods can be used to wait for the job to complete and to iterate over the results.
func (*Query) Done ¶
func (q *Query) Done(opts ...gax.CallOption) <-chan struct{}
Done returns a channel that is closed when the query has completed. It can be used in a select statement to perform non-blocking waits.
Example:
select {
case <-q.Done():
if err := q.Err(); err != nil {
// Handle error.
}
// Query is complete.
case <-time.After(30*time.Second):
// Timeout logic
default:
// Query is still running.
}
func (*Query) Err ¶
Err returns the final error state of the query. It is only valid to call Err after the channel returned by Done has been closed. If the query completed successfully, Err returns nil.
func (*Query) JobReference ¶
func (q *Query) JobReference() *bigquerypb.JobReference
JobReference returns a reference to the query job. This will be nil until the query job has been successfully submitted.
func (*Query) QueryID ¶
QueryID returns the auto-generated ID for the query. This is only populated for stateless queries (i.e. those started via jobs.query) after the query has been submitted.
func (*Query) Read ¶
func (q *Query) Read(ctx context.Context, opts ...ReadOption) (*RowIterator, error)
Read returns a RowIterator for the query results.
func (*Query) Schema ¶
func (q *Query) Schema() *bigquerypb.TableSchema
Schema returns the schema of the query results. This will be nil until the query has completed and the schema is available.
type ReadOption ¶
type ReadOption func(*readState)
ReadOption is an option for reading query results.
func WithPageToken ¶
func WithPageToken(t string) ReadOption
WithPageToken sets the page token for reading query results.
type RowIterator ¶
type RowIterator struct {
}
RowIterator is an iterator over the results of a query.
func (*RowIterator) Next ¶
func (it *RowIterator) Next() (*Row, error)
Next returns the next row from the results.
Source Files