flipside

Documentation

Overview

Package flipside provides convenience wrappers to work with flipside.xyz's REST API. https://api-docs.flipsidecrypto.xyz/

Package flipside provides convenience wrappers to work with flipside.xyz's REST API.

Index

• type Config
  • func NewFromSecret(ctx context.Context, apiKey *secrets.Secret) (*Config, error)
  • func (cfg *Config) AwaitQueryRunExecution(ctx context.Context, queryRunId QueryRunID, initialBackoff time.Duration, ...) (*QueryRun, error)
  • func (cfg *Config) AwaitQueryRunSuccess(ctx context.Context, queryRunId QueryRunID, initialBackoff time.Duration, ...) error
  • func (cfg *Config) CreateQueryRun(ctx context.Context, sql string) (*CreateQueryRunResponse, error)
  • func (cfg *Config) FetchQueryResults(ctx context.Context, token string, pageNumber int) (*QueryExecutionResponse, error)
  • func (cfg *Config) GetQueryRun(ctx context.Context, id QueryRunID) (*QueryRun, error)
  • func (cfg *Config) SubmitQuery(ctx context.Context, sql string) (*QuerySubmissionResponse, error)
• type CreateQueryRunResponse
• type Hours
  • func (h Hours) MarshalJSON() ([]byte, error)
• type Minutes
  • func (m Minutes) MarshalJSON() ([]byte, error)
• type QueryExecutionResponse
  • func (resp *QueryExecutionResponse) Unmarshal(v any) (retErr error)
  • func (r *QueryExecutionResponse) WriteCSV(w io.Writer) error
• type QueryRequest
• type QueryRun
• type QueryRunID
• type QueryRunResults
  • func FetchQueryResults[T any](ctx context.Context, cfg *Config, queryRunId QueryRunID) ([]*QueryRunResults[T], error)
  • func GetQueryRunResults[T any](ctx context.Context, cfg *Config, queryRunId QueryRunID, pageNumber int) (*QueryRunResults[T], error)
• type QuerySubmissionResponse
• type ResultsPage
• type SQLStatement
• type Tags

Types

type Config

type Config struct {
	APIKey        string
	BackoffFactor float64
}

Config configures the flipside wrapper.

func NewFromSecret

func NewFromSecret(ctx context.Context, apiKey *secrets.Secret) (*Config, error)

NewFromSecret creates a new Flipside config from a secret API key.

func (*Config) AwaitQueryRunExecution

func (cfg *Config) AwaitQueryRunExecution(ctx context.Context, queryRunId QueryRunID, initialBackoff time.Duration, backoffFactor float64) (*QueryRun, error)

AwaitQueryRunExecution waits for a specific query run to complete, i.e. until its state changes. The state is checked with exponential backoff.

func (*Config) AwaitQueryRunSuccess

func (cfg *Config) AwaitQueryRunSuccess(ctx context.Context, queryRunId QueryRunID, initialBackoff time.Duration, backoffFactor float64) error

AwaitQueryRunSuccess waits for a specific query run to complete successfully. Unsuccessful queries will return an error.

func (*Config) CreateQueryRun

func (cfg *Config) CreateQueryRun(ctx context.Context, sql string) (*CreateQueryRunResponse, error)

CreateQueryRun submits an SQL query to flipside and creates a new query run. The query run is not executed immediately but will be queued for execution. Information about the query run can be retrieved with GetQueryRun. The query run will be created with the default data source, data provider, results TTL and max age.

func (*Config) FetchQueryResults

func (cfg *Config) FetchQueryResults(ctx context.Context, token string, pageNumber int) (*QueryExecutionResponse, error)

FetchQueryResults fetches the query results for a previously submitted query. The query token is returned by the SubmitQuery.

func (*Config) GetQueryRun

func (cfg *Config) GetQueryRun(ctx context.Context, id QueryRunID) (*QueryRun, error)

GetQueryRun retrieves the details of a specific query run identified by QueryRunID. The QueryRunID is returned by CreateQueryRun.

func (*Config) SubmitQuery

func (cfg *Config) SubmitQuery(ctx context.Context, sql string) (*QuerySubmissionResponse, error)

SubmitQuery submits an SQL query to flipside.

type CreateQueryRunResponse

type CreateQueryRunResponse struct {
	QueryRequest QueryRequest `json:"queryRequest"`
	QueryRun     QueryRun     `json:"queryRun"`
	SQLStatement SQLStatement `json:"sqlStatement"`
}

type Hours

type Hours time.Duration

Hours is a duration that is serialized as float representing hours.

func (Hours) MarshalJSON

func (h Hours) MarshalJSON() ([]byte, error)

type Minutes

type Minutes time.Duration

Minutes is a duration that is serialized as float representing minutes.

func (Minutes) MarshalJSON

func (m Minutes) MarshalJSON() ([]byte, error)

type QueryExecutionResponse

type QueryExecutionResponse struct {
	Results      [][]interface{} `json:"results"`
	ColumnLabels []string        `json:"columnLabels"`
	ColumnTypes  []string        `json:"columnTypes"`
	Status       string          `json:"status"`
	PageNumber   int             `json:"pageNumber"`
	PageSize     int             `json:"pageSize"`
	StartedAt    time.Time       `json:"startedAt"`
	EndedAt      time.Time       `json:"endedAt"`
}

QueryExecutionResponse encodes flipside's response for a query execution.

func (*QueryExecutionResponse) Unmarshal

func (resp *QueryExecutionResponse) Unmarshal(v any) (retErr error)

Unmarshal parses the raw flipside query results and writes it into the given pointer. The data is parsed by creating an intermediate CSV representation (using `WriteCSV`) and unmarshalling this with `gocsv`. CSV struct tags are thus used to match columns as labelled in `QueryExecutionResponse.ColumnLabels`.

func (*QueryExecutionResponse) WriteCSV

func (r *QueryExecutionResponse) WriteCSV(w io.Writer) error

WriteCSV writes flipside query data as CSV. This uses `QueryExecutionResponse.ColumnLabels` as headers and `QueryExecutionResponse.Results` as rows.

type QueryRequest

type QueryRequest struct {
	ID                string     `json:"id"`
	SQLStatementID    string     `json:"sqlStatementId"`
	UserID            string     `json:"userId"`
	Tags              Tags       `json:"tags"`
	MaxAgeMinutes     Minutes    `json:"maxAgeMinutes"`
	ResultsTTLHours   Hours      `json:"resultTTLHours"`
	UserSkipCache     bool       `json:"userSkipCache"`
	TriggeredQueryRun bool       `json:"triggeredQueryRun"`
	QueryRunID        QueryRunID `json:"queryRunId"`
	CreatedAt         time.Time  `json:"createdAt"`
	UpdatedAt         time.Time  `json:"updatedAt"`
}

QueryRequest is part of the response of a query run creation and identifies the request to create a new query.

type QueryRun

type QueryRun struct {
	ID                    QueryRunID  `json:"id"`
	SQLStatementID        string      `json:"sqlStatementId"`
	State                 string      `json:"state"`
	Path                  string      `json:"path"`
	FileCount             int         `json:"fileCount"`
	LastFileNumber        *int        `json:"lastFileNumber"`
	FileNames             string      `json:"fileNames"`
	ErrorName             string      `json:"errorName"`
	ErrorMessage          interface{} `json:"errorMessage"`
	ErrorData             interface{} `json:"errorData"`
	DataSourceQueryID     string      `json:"dataSourceQueryId"`
	DataSourceSessionID   string      `json:"dataSourceSessionId"`
	StartedAt             time.Time   `json:"startedAt"`
	QueryRunningEndedAt   time.Time   `json:"queryRunningEndedAt"`
	QueryStreamingEndedAt time.Time   `json:"queryStreamingEndedAt"`
	EndedAt               time.Time   `json:"endedAt"`
	RowCount              int         `json:"rowCount"`
	TotalSize             string      `json:"totalSize"`
	Tags                  Tags        `json:"tags"`
	DataSourceID          string      `json:"dataSourceId"`
	UserID                string      `json:"userId"`
	CreatedAt             time.Time   `json:"createdAt"`
	UpdatedAt             time.Time   `json:"updatedAt"`
	ArchivedAt            time.Time   `json:"archivedAt"`
}

QueryRun is part of the response of a query run creation and identifies the new query that has been created.

type QueryRunID

type QueryRunID string

QueryRunID identifies a flipside query run.

type QueryRunResults

type QueryRunResults[T any] struct {
	ColumnNames          []string    `json:"columnNames"`
	ColumnTypes          []string    `json:"columnTypes"`
	Rows                 []T         `json:"rows"`
	Page                 ResultsPage `json:"page"`
	SQL                  string      `json:"sql"`
	Format               string      `json:"format"`
	OriginalQueryRun     QueryRun    `json:"originalQueryRun"`
	RedirectedToQueryRun *QueryRun   `json:"redirectedToQueryRun"`
}

QueryRunResults is the response payload of a getQueryRunResults request and holds the execution results of a query.

func FetchQueryResults

func FetchQueryResults[T any](ctx context.Context, cfg *Config, queryRunId QueryRunID) ([]*QueryRunResults[T], error)

FetchQueryResults is a convenience wrapper that waits until a given query succeeds and fetches all its results. The query queryRunId is returned by CreateQueryRun. Unfortunately golang does not allow generic types on methods, so we had to make this a free function instead.

func GetQueryRunResults

func GetQueryRunResults[T any](ctx context.Context, cfg *Config, queryRunId QueryRunID, pageNumber int) (*QueryRunResults[T], error)

GetQueryRunResults retrieves the results of a completed query run with pagination

type QuerySubmissionResponse

type QuerySubmissionResponse struct {
	Token string `json:"token"`
}

QuerySubmissionResponse is returned by flipside after submitting a query and contains the query token that can be used to retrieve the results.

type ResultsPage

type ResultsPage struct {
	CurrentPageNumber int `json:"currentPageNumber"`
	CurrentPageSize   int `json:"currentPageSize"`
	TotalRows         int `json:"totalRows"`
	TotalPages        int `json:"totalPages"`
}

ResultsPage is part of QueryRunResults and holds pagination information.

type SQLStatement

type SQLStatement struct {
	ID             string      `json:"id"`
	StatementHash  string      `json:"statementHash"`
	SQL            string      `json:"sql"`
	ColumnMetadata interface{} `json:"columnMetadata"`
	UserID         string      `json:"userId"`
	Tags           Tags        `json:"tags"`
	CreatedAt      time.Time   `json:"createdAt"`
	UpdatedAt      time.Time   `json:"updatedAt"`
}

SQLStatement is part of the response of a query run creation and identifies the SQL statement that will be executed as part of the run.

type Tags

type Tags = map[string]string

Tags add metadata to a query run.