Skip to content

Latest commit

 

History

History

query

README.md

Query

This package offers a set of predefined protobuf message types to be used as collection query parameters, which are also called collection operators. These types are:

  • infoblox.api.Filtering
  • infoblox.api.Sorting
  • infoblox.api.Pagination
  • infoblox.api.PageInfo(used in response)
  • infoblox.api.FieldSelection
  • infoblox.api.Searching

Enabling collection operators in your application

In order to get collection operators in your app you need the following:

  • Add collection operator types to a request message. You're free to use any subset of them.
import "github.com/infobloxopen/atlas-app-toolkit/query/collection_operators.proto";

message MyListRequest {
    infoblox.api.Filtering filtering = 1;
    infoblox.api.Sorting sorting = 2;
    infoblox.api.Pagination pagination = 3;
    infoblox.api.FieldSelection fields = 4;
    infoblox.api.Searching searching = 5;
}
  • Enable gateway.ClientUnaryInterceptor and gateway.MetadataAnnotator in your gRPC gateway. This will make collection operators to be automatically parsed on gRPC gateway side. If you're using our server wrapper, you need to explicitly set only gateway.ClientUnaryInterceptor since gateway.MetadataAnnotator is enabled by default.
server.WithGateway(
  gateway.WithDialOptions(
    []grpc.DialOption{grpc.WithInsecure(), grpc.WithUnaryInterceptor(
      grpc_middleware.ChainUnaryClient(
        []grpc.UnaryClientInterceptor{gateway.ClientUnaryInterceptor...})},
      ),
  )
)

Filtering

The syntax of REST representation of infoblox.api.Filtering is the following.

REST Query Parameter Description
_filter A string expression containing JSON tags, literal values, and logical operators.

Literal values include numbers (integer and floating-point), quoted (both single- or double-quoted) literal strings, “null” , arrays with numbers (integer and floating-point) and arrays with quoted (both single- or double-quoted) literal strings. The following operators are commonly used in filter expressions.

Operator Description Example
== eq Equal
!= ne Not Equal
> gt Greater Than
>= ge Greater Than or Equal To
< lt Less Than
<= le Less Than or Equal To
and Logical AND price <= 200 and price > 3.5
~ match Matches Regex
!~ nomatch Does Not Match Regex
or Logical OR price <= 3.5 or price > 200
not Logical NOT not price <= 3.5
() Grouping (priority == 1 or city == ‘Santa Clara’) and price > 100
:= ieq Insensitive equal
in Check existence in set city in [‘Santa Clara’, ‘New York’] or price in [1,2,3]

In order to escape string literal delimiter duplicate it, e.g. for single-quoted string literals: _filter=field == 'dup single quote '' ', for double-quoted literals: _filter=field == "dup double quote "" ".

JSONB Filtering

Also our filtering support custom jsonb conditions if you use postgresql as a database. In order to use this feathure you have to use special type Jsonb. If you plan to use special jsonb filtering on a field it's type should be *dialects.Jsonb. Syntax for jsonb filtering is similar to the one you use for StringCondition and StringArrayCondition, as well as you can use operators from StringCondition and StringArrayCondition.

Example:

Consider that you have a following object where info field is a jsonb field:

{
 name: "my object",
 info: {
     Address: {
         "City": "Tacoma",
         "Country": "USA"
     }
 }
}

Filterting request with jsonb query will look like:

...?_filter=info.Address.City=='Tacoma'

if you want to compare enclosed object with json you are able to write:

...?_filter=info.Address=='{"City": "Tacoma", "Country": "USA"}'

Note: if you decide to use toolkit provided infoblox.api.Filtering proto type, then you'll not be able to use vanilla swagger schema generation, since this plugin doesn't work with recursive nature of infoblox.api.Filtering. In this case you can use our fork which has a fix for this issue. You can also use atlas-gentool which contains both versions of the plugin.

Sorting

The syntax of REST representation of infoblox.api.Sorting is the following.

Request Parameter Description Example
_order_by A comma-separated list of JSON tag names. The sort direction can be specified by a suffix separated by whitespace before the tag name. The suffix “asc” sorts the data in ascending order. The suffix “desc” sorts the data in descending order. If no suffix is specified the data is sorted in ascending order. work_address.addresss desc,first_name

Pagination

The syntax of REST representation of infoblox.api.Pagination and infoblox.api.PageInfo is the following.

Paging Mode Request Parameters Response Parameters Description
Client-driven paging _offset The integer index (zero-origin) of the offset into a collection of resources. If omitted or null, the value is assumed to be “0”.
_limit The integer number of resources to be returned in the response. The service may impose maximum value. If omitted, the service may impose a default value.
_offset The service may optionally* include the offset of the next page of resources. A null value indicates no more pages.
_size The service may optionally include the total number of resources being paged.
Server-driven paging _page_token The service-defined string used to identify a page of resources. A null value indicates the first page.
_page_token The service response should contain a string to indicate the next page of resources. A null value indicates no more pages.
_size The service may optionally include the total number of resources being paged.

Field Selection

The syntax of REST representation of infoblox.api.FieldSelection is the following.

Request Parameter Description Example
_fields A comma-separated list of JSON tag names. work_address.addresss,first_name

As it is not possible to completely remove all the fields(such as primitives) from proto.Message on gRPC server side, fields are additionally truncated on gRPC Gateway side. This is done by gateway.ResponseForwarder.

Field Presence

Using the toolkit's server package functionality, you can optionally enable automatic filling of a google.protobuf.FieldMask within the gRPC Gateway.

As a prerequisite, the request passing through the gateway must match the list of given HTTP methods (e.g. POST, PUT, PATCH) and contain a FieldMask at the top level.

import "google/protobuf/field_mask.proto";
message MyRequest {
  bytes data = 1;
  google.protobuf.FieldMask fields = 2;
}

To enable the functionality, use the following args in the WithGateway method:

server.WithGateway(
  gateway.WithGatewayOptions(
    runtime.WithMetadata(gateway.NewPresenceAnnotator("POST", ...)),
    ...
  ),
  gateway.WithDialOptions(
    []grpc.DialOption{grpc.WithInsecure(), grpc.WithUnaryInterceptor(
      grpc_middleware.ChainUnaryClient(
        []grpc.UnaryClientInterceptor{gateway.ClientUnaryInterceptor, gateway.PresenceClientInterceptor()}...)},
      ),
  )
)

Searching

The syntax of REST representation of infoblox.api.Searching is the following.

Request Parameter Description
_fts A string expression which performs a full-text-search on the DB

Full-text-search is an optimized mechanism to retrieve data from the DB efficiently when the user is only aware of some portion of the data they are searching.

Example:

Consider that you have the following objects:

{
 name: "my first object",
 city: "Santa Clara",
 country: "USA"
},
{
 name: "my second object",
 city: "Tacoma",
 country: "USA"
}

If "name" is provided as a field for FTS, the Searching query will look like:

...?_fts=my first object

In this case, only the first object would be returned.

If "country" is provided as a field for FTS, the Searching query will look like:

...?_fts=USA

In this case, both the objects would be returned.