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.
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 AIP-132 order by clause parser.
Index ¶
- func NewLexer(input string) *filterLexer
- type Arg
- type Column
- type 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
- type Comparable
- type Expression
- type Factor
- type FieldPath
- type Filter
- type Member
- type OrderBy
- type QueryParameter
- type Restriction
- type Sequence
- type Simple
- type Table
- func (t *Table) FilterableColumnByFieldPath(path FieldPath) (*Column, error)
- func (t *Table) OrderByClause(order []OrderBy) (string, error)
- func (t *Table) SortableColumnByFieldPath(path FieldPath) (*Column, error)
- func (t *Table) WhereClause(filter *Filter, parameterPrefix string) (string, []QueryParameter, error)
- type TableBuilder
- type Term
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Arg ¶
type Arg struct { Comparable *Comparable // Composite is a parenthesized expression, commonly used to group // terms or clarify operator precedence. // // Example: `(msg.endsWith('world') AND retries < 10)` Composite *Expression }
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 (*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 Comparable ¶
type Comparable struct {
Member *Member
}
Comparable may either be a member or function. As functions are not currently supported, it is always a member.
func (*Comparable) String ¶
func (v *Comparable) String() string
type Expression ¶
type Expression struct { // Sequences are always joined by an AND operator Sequences []*Sequence }
Expressions may either be a conjunction (AND) of sequences or a simple sequence.
Note, the AND is case-sensitive.
Example: `a b AND c AND d`
The expression `(a b) AND c AND d` is equivalent to the example.
func (*Expression) String ¶
func (v *Expression) String() string
type Factor ¶
type Factor struct { // Terms are always joined by an OR operator Terms []*Term }
Factors may either be a disjunction (OR) of terms or a simple term.
Note, the OR is case-sensitive.
Example: `a < 10 OR a >= 100`
type FieldPath ¶
type FieldPath struct {
// contains filtered or unexported fields
}
FieldPath represents the path to a field in a message.
For example, for the given message:
message MyThing { message Bar { string foobar = 2; } string foo = 1; Bar bar = 2; map<string, Bar> named_bars = 3; }
Some valid paths would be: foo, bar.foobar and named_bars.`bar-key`.foobar.
func NewFieldPath ¶
NewFieldPath initialises a new field path with the given segments.
type Filter ¶
type Filter struct {
Expression *Expression // Optional, may be nil.
}
Filter, possibly empty
func ParseFilter ¶
Parse an AIP-160 filter string into an AST.
type Member ¶
Member expressions are either value or DOT qualified field references.
Example: `expr.type_map.1.type`
type OrderBy ¶
type OrderBy struct { // The field path. This is the path of the field in the // resource message that the AIP-132 List RPC is listing. FieldPath FieldPath // Whether the field should be sorted in descending order. Descending bool }
OrderBy represents a part of an AIP-132 order_by clause.
func MergeWithDefaultOrder ¶
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.
func ParseOrderBy ¶
ParseOrderBy parses an AIP-132 order_by list. The method validates the syntax is correct and each identifier appears at most once, but it does not validate the identifiers themselves are valid.
type QueryParameter ¶
QueryParameter represents a query parameter.
type Restriction ¶
type Restriction struct { Comparable *Comparable // Comparators supported by list filters: <=, <. >=, >, !=, =, : Comparator string Arg *Arg }
Restrictions express a relationship between a comparable value and a single argument. When the restriction only specifies a comparable without an operator, this is a global restriction.
Note, restrictions are not whitespace sensitive.
Examples: * equality : `package=com.google` * inequality : `msg != 'hello'` * greater than : `1 > 0` * greater or equal : `2.5 >= 2.4` * less than : `yesterday < request.time` * less or equal : `experiment.rollout <= cohort(request.user)` * has : `map:key` * global : `prod`
In addition to the global, equality, and ordering operators, filters also support the has (`:`) operator. The has operator is unique in that it can test for presence or value based on the proto3 type of the `comparable` value. The has operator is useful for validating the structure and contents of complex values.
func (*Restriction) String ¶
func (v *Restriction) String() string
type Sequence ¶
type Sequence struct { // Factors are always joined by an (implicit) AND operator Factors []*Factor }
Sequence is composed of one or more whitespace (WS) separated factors.
A sequence expresses a logical relationship between 'factors' where the ranking of a filter result may be scored according to the number factors that match and other such criteria as the proximity of factors to each other within a document.
When filters are used with exact match semantics rather than fuzzy match semantics, a sequence is equivalent to AND.
Example: `New York Giants OR Yankees`
The expression `New York (Giants OR Yankees)` is equivalent to the example.
type Simple ¶
type Simple struct { Restriction *Restriction // Composite is a parenthesized expression, commonly used to group // terms or clarify operator precedence. // // Example: `(msg.endsWith('world') AND retries < 10)` Composite *Expression }
Simple expressions may either be a restriction or a nested (composite) expression.
type Table ¶
type Table struct {
// contains filtered or unexported fields
}
Table represents the schema of a Database table, view or query.
func (*Table) FilterableColumnByFieldPath ¶
FilterableColumnByFieldPath returns the database name of the filterable column with the given field path.
func (*Table) OrderByClause ¶
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 ¶
SortableColumnByFieldPath returns the sortable database column with the given externally-visible field path.
func (*Table) WhereClause ¶
func (t *Table) WhereClause(filter *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 (*TableBuilder) WithColumns ¶
func (t *TableBuilder) WithColumns(columns ...*Column) *TableBuilder
WithColumns specifies the columns in the table.
type Term ¶
Terms may either be unary or simple expressions.
Unary expressions negate the simple expression, either mathematically `-` or logically `NOT`. The negation styles may be used interchangeably.
Note, the `NOT` is case-sensitive and must be followed by at least one whitespace (WS).
Examples: * logical not : `NOT (a OR b)` * alternative not : `-file:".java"` * negation : `-30`