aip

Documentation

Overview

Package aip contains utilities used to comply with API Improvement Proposals (AIPs) from https://google.aip.dev/. This includes an AIP-160 filter parser and SQL generator and AIP-132 order by clause parser and SQL generator.

Index

• func MergeWithDefaultOrder(defaultOrder []aip132.OrderBy, order []aip132.OrderBy) []aip132.OrderBy
• type Column
• type ColumnBuilder
  • func NewColumn() *ColumnBuilder
  • func (c *ColumnBuilder) Array() *ColumnBuilder
  • func (c *ColumnBuilder) Bool() *ColumnBuilder
  • func (c *ColumnBuilder) Build() *Column
  • func (c *ColumnBuilder) Filterable() *ColumnBuilder
  • func (c *ColumnBuilder) FilterableImplicitly() *ColumnBuilder
  • func (c *ColumnBuilder) KeyValue() *ColumnBuilder
  • func (c *ColumnBuilder) Sortable() *ColumnBuilder
  • func (c *ColumnBuilder) WithArgumentSubstitutor(f func(sub string) string) *ColumnBuilder
  • func (c *ColumnBuilder) WithDatabaseName(name string) *ColumnBuilder
  • func (c *ColumnBuilder) WithFieldPath(segments ...string) *ColumnBuilder
• type ColumnType
  • func (t ColumnType) String() string
• type QueryParameter
• type Table
  • func (t *Table) FilterableColumnByFieldPath(path aip132.FieldPath) (*Column, error)
  • func (t *Table) OrderByClause(order []aip132.OrderBy) (string, error)
  • func (t *Table) SortableColumnByFieldPath(path aip132.FieldPath) (*Column, error)
  • func (t *Table) WhereClause(filter *aip160.Filter, parameterPrefix string) (string, []QueryParameter, error)
• type TableBuilder
  • func NewTable() *TableBuilder
  • func (t *TableBuilder) Build() *Table
  • func (t *TableBuilder) WithColumns(columns ...*Column) *TableBuilder

Functions

func MergeWithDefaultOrder

func MergeWithDefaultOrder(defaultOrder []aip132.OrderBy, order []aip132.OrderBy) []aip132.OrderBy

MergeWithDefaultOrder merges the specified order with the given defaultOrder. The merge occurs as follows:

• Ordering specified in `order` takes precedence.
• For columns not specified in the `order` that appear in `defaultOrder`, ordering is applied in the order they apply in defaultOrder.

Types

type Column

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

Column represents the schema of a Database column.

type ColumnBuilder

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

func NewColumn

func NewColumn() *ColumnBuilder

NewColumn starts building a new column.

func (*ColumnBuilder) Array

func (c *ColumnBuilder) Array() *ColumnBuilder

Array specifies this column is an array. The value can be queried with ':'. The operator matches if any element of the array matches. Example query: column:value

func (*ColumnBuilder) Bool

func (c *ColumnBuilder) Bool() *ColumnBuilder

Bool specifies this column has bool type in the database.

func (*ColumnBuilder) Build

func (c *ColumnBuilder) Build() *Column

Build returns the built column.

func (*ColumnBuilder) Filterable

func (c *ColumnBuilder) Filterable() *ColumnBuilder

Filterable specifies this column can be filtered on.

func (*ColumnBuilder) FilterableImplicitly

func (c *ColumnBuilder) FilterableImplicitly() *ColumnBuilder

FilterableImplicitly specifies this column can be filtered on implicitly. This means that AIP-160 filter expressions not referencing any particular field will try to search in this column.

func (*ColumnBuilder) KeyValue

func (c *ColumnBuilder) KeyValue() *ColumnBuilder

KeyValue specifies this column is an array of structs with two string members: key and value. The key is exposed as a field on the column name, the value can be queried with :, = and != Example query: tag.key=value

func (*ColumnBuilder) Sortable

func (c *ColumnBuilder) Sortable() *ColumnBuilder

Sortable specifies this column can be sorted on.

func (*ColumnBuilder) WithArgumentSubstitutor

func (c *ColumnBuilder) WithArgumentSubstitutor(f func(sub string) string) *ColumnBuilder

WithArgumentSubstitutor specifies a substitution that should happen to the user-specified filter argument before it is matched against the database value. If this option is enabled, the filter operators permitted will be limited to = (equals) and != (not equals).

func (*ColumnBuilder) WithDatabaseName

func (c *ColumnBuilder) WithDatabaseName(name string) *ColumnBuilder

WithDatabaseName specifies the database name of the column. Important: Only pass safe values (e.g. compile-time constants) to this field. User input MUST NOT flow to this field, as it will be used directly in SQL statements and would allow the user to perform SQL injection attacks.

func (*ColumnBuilder) WithFieldPath

func (c *ColumnBuilder) WithFieldPath(segments ...string) *ColumnBuilder

WithFieldPath specifies the field path the column maps to in the returned resource. Field paths are described in AIP-161.

For convenience, the field path is described here as a set of segments where each segment is joined by the traversal operator (.). E.g. the field path "metrics.`some-metric`.value" would be specified as ["metrics", "some-metric", "value"].

type ColumnType

type ColumnType int32

ColumnType is an enum for the type of a column. Valid values are in the const block above.

const (
	// ColumnTypeString is a column of type string.
	ColumnTypeString ColumnType = iota
	// ColumnTypeBool is a column of type boolean.  NULL values are mapped to FALSE.
	ColumnTypeBool = iota
)

func (ColumnType) String

func (t ColumnType) String() string

type QueryParameter

type QueryParameter struct {
	Name  string
	Value string
}

QueryParameter represents a query parameter.

type Table

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

Table represents the schema of a Database table, view or query.

func (*Table) FilterableColumnByFieldPath

func (t *Table) FilterableColumnByFieldPath(path aip132.FieldPath) (*Column, error)

FilterableColumnByFieldPath returns the database name of the filterable column with the given field path.

func (*Table) OrderByClause

func (t *Table) OrderByClause(order []aip132.OrderBy) (string, error)

OrderByClause returns a Standard SQL Order by clause, including "ORDER BY" and trailing new line (if an order is specified). If no order is specified, returns "".

The returned order clause is safe against SQL injection; only strings appearing from Table appear in the output.

func (*Table) SortableColumnByFieldPath

func (t *Table) SortableColumnByFieldPath(path aip132.FieldPath) (*Column, error)

SortableColumnByFieldPath returns the sortable database column with the given externally-visible field path.

func (*Table) WhereClause

func (t *Table) WhereClause(filter *aip160.Filter, parameterPrefix string) (string, []QueryParameter, error)

WhereClause creates a Standard SQL WHERE clause fragment for the given filter.

The fragment will be enclosed in parentheses and does not include the "WHERE" keyword. For example: (column LIKE @param1) Also returns the query parameters which need to be given to the database.

All field names are replaced with the safe database column names from the specified table. All user input strings are passed via query parameters, so the returned query is SQL injection safe.

type TableBuilder

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

func NewTable

func NewTable() *TableBuilder

NewTable starts building a new table.

func (*TableBuilder) Build

func (t *TableBuilder) Build() *Table

Build returns the built table.

func (*TableBuilder) WithColumns

func (t *TableBuilder) WithColumns(columns ...*Column) *TableBuilder

WithColumns specifies the columns in the table.