dql

package module
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Jul 4, 2024 License: MIT Imports: 6 Imported by: 0

README

DQL Golang SDK

DQL Go SDK

GoDoc MIT License

Install

  • Go 1.18+
go get github.com/GuanceCloud/dql-go

Usage

import _ "github.com/GuanceCloud/dql-go"

Examples

See simple examples under examples directory or find examples in query_test.go.

Documentation

Overview

Package dql wraps DQL query SDK.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildDQL 

func BuildDQL(dqlStr string, opts ...DQLOption) (*dql, error)

BuildDQL used to build a DQL query with one or more options. dqlStr is the basic DQL query string.

func MustBuildDQL 

func MustBuildDQL(dql string, opts ...DQLOption) *dql

MustBuildDQL build a DQL query, and panic on any error. Most of the time, the build will not fail, we can use the Must function without worry.

Types

type AsyncSearchTaskPayload added in v0.1.1 

type AsyncSearchTaskPayload struct {
	CreateTime    time.Time
	SearchTimeout string
	AsyncID       string
	Timeout       string
	Wsuuid        string
}

type Client 

type Client struct {
	// contains filtered or unexported fields
}

A Client is the DQL query client connecting to a exist Datakit or directly to Dataway(and the token required).

func NewClient 

func NewClient(host string) *Client

NewClient create a Datakit/Dataway client with IP:Port. For example, local default Datakit host is localhost:9529, for directly to dataway, the default host is openway.guance.com.

func (*Client) Query 

func (c *Client) Query(opts ...QueryOption) (*Result, error)

Query send one or more DQL query to Datakit. We can build DQL within QueryOptions.

type DQLOption 

type DQLOption func(*dql)

DQLOption used to set various DQL options.

func WithAlignTime added in v0.1.2 

func WithAlignTime(on bool) DQLOption

WithAlignTime enable time alignment for query result.

func WithAsync 

func WithAsync(on bool) DQLOption

WithAsync set async query.

func WithAsyncID added in v0.1.1 

func WithAsyncID(id string) DQLOption

WithAsyncID fetch async query result on the id.

func WithAsyncTimeout 

func WithAsyncTimeout(du time.Duration) DQLOption

WithAsyncTimeout set async query timeout.

func WithConditions 

func WithConditions(conditions string) DQLOption

WithConditions set extra where-condtions to DQL.

func WithCursorTime added in v0.1.2 

func WithCursorTime(n int64) DQLOption

WithCursorTime set cursort timestamp for paging. The timestamp n can be s/ms/us, and the backend will guess the unit of the timestamp.

func WithDisableExpensiveQuery deprecated 

func WithDisableExpensiveQuery(on bool) DQLOption

WithDisableExpensiveQuery disable/enable expensive query. For left wildcard like following will trigger a expensive query. 

L::some_source { f1 = wildcard('*xx') }

NOTE: Disable all expensive query are a good manner to protect your worksapce.

Deprecated: Option removed for DQL.

func WithDisableMultipleField 

func WithDisableMultipleField(on bool) DQLOption

WithDisableMultipleField disable/enable query multiple field in single DQL.

func WithDisableQueryParse 

func WithDisableQueryParse(on bool) DQLOption

WithDisableQueryParse disable/enable query parse.

func WithDisableSLimit 

func WithDisableSLimit(on bool) DQLOption

WithDisableSLimit disable/enable default slimit.

func WithHighlight 

func WithHighlight(on bool) DQLOption

WithHighlight enable/disable highlight on query result.

func WithLargeQuery added in v0.1.2 

func WithLargeQuery(on bool) DQLOption

WithLargeQuery enable/disable large-data-set query. Large-data-set query default enabled, but we can disable it to protect backend storage.

func WithLimit added in v0.1.2 

func WithLimit(n int64) DQLOption

WithLimit set max returned point's. Default is 1000.

func WithMaskVisible 

func WithMaskVisible(on bool) DQLOption

WithMaskVisible set visible/hide on sensitive fields.

func WithMaxDuration 

func WithMaxDuration(du time.Duration) DQLOption

WithMaxDuration set DQL max time range, this option used to avoid unexpected too-large query. If time range in DQL exceed max duration, there will be a query error returned. For example, following DQL will fail if max duration set to 1 hour: 

L::some_source [1d:] # query latest 24h logging

We will get a error like: 

parse error: time range should less than 1h0m0s

func WithMaxPoint 

func WithMaxPoint(n int) DQLOption

WithMaxPoint used to control max query points under group by, for example: 

L::re(`.*`):(fill(count(__docid), 0) AS count) [1d] BY status

All logs are group by its status, each status(bucket) may have different number of logs, and we can limit only n points in each status.

func WithMultipleWorkspaceRules added in v0.1.2 

func WithMultipleWorkspaceRules(rules ...*WorkspaceIndexRule) DQLOption

WithMultipleWorkspaceRules query among multiple workspaces.

Workspace rules example: 

rules := []*WorkspaceIndexRule{
	&WorkspaceIndexRule{
		WorkspaceUUID: "wksp_4b57c7bab38e4a2d9630xxxxxxxxxxxx",
		IndexName:     "default",
		Rules:         any{}, // See rules in WithRoleRules
	},
}

func WithOffset 

func WithOffset(n int) DQLOption

WithOffset used to query next page points.

func WithOptimized added in v0.1.1 

func WithOptimized(on bool) DQLOption

WithOptimized enable optimize on query. For example, if query 7 days data, the query will only response the first index data. If order by ASC, the first index is the oldest index.

NOTE: not available on M::.

func WithOrderBy 

func WithOrderBy(k string, order OrderByOrder) DQLOption

WithOrderBy used to set order-by on point.

func WithOutputFormat 

func WithOutputFormat(of OutputFormat) DQLOption

WithOutputFormat set output format, currently only support LineProtocol.

func WithProfile added in v0.1.1 

func WithProfile(on bool) DQLOption

WithProfile enable profiling. Only available for OpenSearch backend.

func WithQueryType added in v0.1.2 

func WithQueryType(t string) DQLOption

WithQueryType set query type, only "dql" or "promql" are allowed.

func WithRoleRules added in v0.1.2 

func WithRoleRules(rules map[string][]QueryRule) DQLOption

WithRoleRules set role rules for the query.

Rules example: 

rules := map[string][]QueryRule{
	"logging": []QueryRule{ // rule for query logging(aka L::) data.
	QueryRule{
			Rule:  `fruit IN ['apple', 'orange']`,
			Index: []string{"my-logging-index-name"},
		},
	},
}

func WithSLimit 

func WithSLimit(n int) DQLOption

WithSLimit used to limit max query time series.

func WithSOffset 

func WithSOffset(n int) DQLOption

WithSOffset used to query next page of series.

func WithSOrderBy added in v0.1.2 

func WithSOrderBy(k string, order OrderByOrder) DQLOption

WithSOrderBy used to set order-by on series.

func WithSampling added in v0.1.2 

func WithSampling(on bool) DQLOption

WithSampling used to enable/disable sampling of the query result.

func WithSearchAfter 

func WithSearchAfter(after ...any) DQLOption

WithSearchAfter used to set search-after of the DQL query.

func WithShowLabel deprecated 

func WithShowLabel(on bool) DQLOption

WithShowLabel will show-label in query result. NOTE: Only available on query Object(O::).

Deprecated: this option is dropped.

func WithStepInterval added in v0.1.2 

func WithStepInterval(n int64) DQLOption

WithStepInterval set time step interval for time-aggregate query.

func WithTimeRange 

func WithTimeRange(start, end int) DQLOption

WithTimeRange used to set time range of the DQL query. start and end are UNIX timestamp in ms.

func WithTimeout added in v0.1.1 

func WithTimeout(du time.Duration) DQLOption

WithTimeout set query timeout.

type DQLResult 

type DQLResult struct {
	Series []*Row `json:"series"`

	// Base64 encoded lineprotocol output
	Points []string `json:"points"`

	GroupByList []string `json:"group_by,omitempty"`

	SearchAfter []interface{} `json:"search_after,omitempty"`

	Cost         string      `json:"cost"`
	RawQuery     string      `json:"raw_query,omitempty"`
	QueryParse   interface{} `json:"query_parse,omitempty"`
	QueryWarning string      `json:"query_warning,omitempty"`

	Totalhits   int64 `json:"total_hits,omitempty"`
	FilterCount int64 `json:"filter_count,omitempty"`

	// Async query ID
	AsyncID string `json:"async_id,omitempty"`

	// Logging index name
	IndexName string `json:"index_name"`

	// Logging storage type(sls/outer_sls/es)
	IndexStoreType string `json:"index_store_type"`

	// Query type(influxdb/tdengine/guancedb)
	QueryType string `json:"query_type"`

	// Async query still running or not
	IsRunning  bool   `json:"is_running"`
	Complete   bool   `json:"complete"`
	IndexNames string `json:"index_names"` // index names
}

A DQLResult is a single DQL's query result.

type DorisIndices added in v0.1.2 

type DorisIndices struct {
	TenantID  string `json:"tenant_id"`
	IndexName string `json:"index_name"`
	Condition string `json:"conditions"`
}

type OrderByOrder 

type OrderByOrder int

A OrderByOrder is the order-by option, DESC or ASC. 

const (
	ASC OrderByOrder = iota
	DESC
)

The order-by options: asc and desc.

func (OrderByOrder) String 

func (o OrderByOrder) String() string

String is the string-representation of DESC and ASC.

type OutputFormat 

type OutputFormat int

A OutputFormat is the query result format. 

const (
	LineProtocol OutputFormat = iota
)

Query result formats.

func (OutputFormat) String 

func (of OutputFormat) String() string

String used to get the output format in string representation.

type QueryOption 

type QueryOption func(*query)

QueryOption used to set various query options.

func WithEchoExplain 

func WithEchoExplain(on bool) QueryOption

WithEchoExplain used to echo the translated query of the DQL.

func WithHTTPS added in v0.1.1 

func WithHTTPS(on bool) QueryOption

WithHTTPS are required if we want to send the query to public openway.

func WithQueries 

func WithQueries(arr ...*dql) QueryOption

WithQueries used to send one or more DQLs to a query request.

func WithToken added in v0.1.1 

func WithToken(token string) QueryOption

WithToken enable we send the query to Dataway directly.

type QueryRule added in v0.1.2 

type QueryRule struct {
	Rule  string   `json:"rule"`
	Index []string `json:"indexes"`
}

type Result 

type Result struct {
	ErrorCode string       `json:"error_code,omitempty"`
	Message   string       `json:"message,omitempty"`
	Content   []*DQLResult `json:"content"`
}

A Result is the query result of DQL request. Within a Result there maybe multiple DQL query result. If there any error on query, we can see them with ErrorCode and Message.

type Row 

type Row struct {
	Name    string            `json:"name,omitempty"`
	Tags    map[string]string `json:"tags,omitempty"`
	Columns []string          `json:"columns,omitempty"`
	Values  [][]interface{}   `json:"values,omitempty"`
	Partial bool              `json:"partial,omitempty"`
}

Row represents a single row returned from the execution of a statement.

type WorkspaceIndexRule added in v0.1.2 

type WorkspaceIndexRule struct {
	WorkspaceUUID string                 `json:"workspace_uuid"`
	IndexName     string                 `json:"index_name"`
	Rules         map[string][]QueryRule `json:"rules"`
}

Source Files

View all Source files

Directories

Path Synopsis
exmaples
simple

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.