v1

Documentation

Overview

Package v1 contains EliasDB REST API Version 1.

Binary Blob control endpoint

/blob

The blob endpoint can be used to store and retrieve binary data to/from automatically allocated storage locatons.

A new binary blob can be stored by sending a POST request. The body should be the binary data to store. The response should have the following structure:

{
	id : <ID of the stored binary blob>
}

/blob/<id>

GET requests can be used to retrieve a binary blobs with a specific ID. Binary blobs can be updated by sending a PUT request and removed by sending a DELETE request.

Cluster control endpoint

/cluster

The cluster endpoint returns cluster state specific information. A GET request returns the cluster state info as a key-value map:

{
    <stateinfo key> : <info value>,
    ...
}

/cluster/join

An instance can join an existing cluster by sending a PUT request to the join endpoint. The body should have the following datastructure:

{
	name    : <Name of an existing cluster member>,
	netaddr : <Network address of an existing cluster member>
}

/cluster/eject

A cluster member can eject another cluster member or itself by sending a PUT request to the eject endpoint. The body should have the following datastructure:

{
	name    : <Name the cluster member to eject>,
}

/cluster/ping

An instance can ping another instance (provided the secret is correct). Cluster membership is not required for this command. The body should have the following datastructure:

{
	name    : <Name of an existing instance>,
	netaddr : <Network address of an existing instance>
}

/cluster/memberinfos

The memberinfos endpoint returns the static member info of every known cluster member. If a member is not reachable its info contains a single key-value pair with the key error and an error message as value. A GET request returns the member info of every member as a key-value map:

{
    <memberinfo key> : <memberinfo value>,
    ...
}

/cluster/log

Returns the latest cluster related log messages. A DELETE call will clear the current log.

EQL parser endpoint

/eql

The EQL endpoint provides direct access to the EQL parser. It can be used to parse a given EQL query into an Abstract Syntax Tree or pretty print a given Abstract Syntax Tree into an EQL query.

A query can be parsed into an Abstract Syntax Tree by sending a POST request. The body should have the following format:

{
	query : <Query to parse>
}

Returns a JSON structure or an error message.

{
	ast : <AST of the given query>
}

An Abstract Syntax Tree can be pretty printed into a query by sending a POST request. The body should have the following format:

{
	ast : <AST to pretty print>
}

Returns a JSON structure or an error message.

{
	query : <Pretty printed query>
}

Graph request endpoint

/graph

The graph endpoint is the main entry point to send and request graph data.

Data can be send by using POST and PUT requests. POST will store data in the datastore and always overwrite any existing data. PUT requests on nodes will only update the given attributes. PUT requests on edges are handled equally to POST requests. Data can be deleted using DELETE requests. The data structure for DELETE requests requires only the key and kind attributes.

A PUT, POST or DELETE request should be send to one of the following endpoints:

/graph/<partition>

A graph with the following datastructure:

{
	nodes : [ { <attr> : <value> }, ... ],
	edges : [ { <attr> : <value> }, ... ]
}

/graph/<partition>/n

A list of nodes:

[ { <attr> : <value> }, ... ]

/graph/<partition>/e

A list of edges:

[ { <attr> : <value> }, ... ]

GET requests can be used to query single or a series of nodes. The endpoints support the limit and offset parameters for lists:

limit  - How many list items to return
offset - Offset in the dataset (0 to <total count>-1)

The total number of entries is returned in the X-Total-Count header when a list is returned.

/graph/<partition>/n/<node kind>/[node key]/[traversal spec]

/graph/<partition>/e/<edge kind>/<edge key>

The return data is a list of objects unless a specific node / edge or a traversal from a specific node is requested. Each object in the list models a node or edge.

[{
    key : <value>,
	...
}]

If a specifc object is requested then the return data is a single object.

{
    key : <value>,
    ...
}

Traversals return two lists containing traversed nodes and edges. The traversal endpoint does NOT support limit and offset parameters. Also the X-Total-Count header is not set.

[
    [ <traversed nodes> ], [ <traversed edges> ]
]

Index query endpoint

/index

The index query endpoint should be used to run index search queries against partitions. Index queries look for words or phrases on all nodes of a given node kind.

A phrase query finds all nodes/edges where an attribute contains a certain phrase. A request url which runs a new phrase search should be of the following form:

/index/<partition>/n/<node kind>?phrase=<phrase>&attr=<attribute>

/index/<partition>/e/<edge kind>?phrase=<phrase>&attr=<attribute>

The return data is a list of node keys:

[ <node key1>, <node key2>, ... ]

A word query finds all nodes/edges where an attribute contains a certain word. A request url which runs a new word search should be of the following form:

/index/<partition>/n/<node kind>?word=<word>&attr=<attribute>

/index/<partition>/e/<edge kind>?word=<word>&attr=<attribute>

The return data is a map which maps node key to a list of word positions:

{
    key : [ <pos1>, <pos2>, ... ],
    ...
}

A value search finds all nodes/edges where an attribute has a certain value. A request url which runs a new value search should be of the following form:

/index/<partition>/n/<node kind>?value=<value>&attr=<attribute>

/index/<partition>/e/<edge kind>?value=<value>&attr=<attribute>

The return data is a list of node keys:

[ <node key1>, <node key2>, ... ]

Find query endpoint

/find

The find query endpoint is a simplified index query which looks up nodes in all partitions which do not start with a _ character. It either searches for a word / phrase or an exact value on all available attributes.

A phrase query finds all nodes/edges where an attribute contains a certain phrase. A request url should be of the following form:

/find?text=<word or phrase value> /find?value=<exact value>

The return data is a map of partitions to node kinds to a list of nodes:

{
    <partition> : {
		<kind> : [ { node1 }, { node2 }, ... ]
		...
	}
    ...
}

GraphQL request endpoint

/graphql /graphql-query

The GraphQL endpoints execute GraphQL queries on EliasDB's datastore. The query endpoint supports only read-queries (i.e. no mutations). EliasDB supports only executable definitions and introspection (i.e. no type system validation).

General database information endpoint

/info

The info endpoint returns general database information such as known node kinds, known attributes, etc ..

The return data is a key-value map:

{
    <info name> : <info value>,
    ...
}

/info/kind/<kind>

The node kind info endpoint returns general information about a known node or edge kind such as known attributes or known edges.

Query endpoint

/query

The query endpoint should be used to run EQL search queries against partitions. The return value is always a list (even if there is only a single entry).

A query result gets an ID and is stored in a cache. The ID is returned in the X-Cache-Id header. Subsequent requests for the same result can use the ID instead of a query.

The endpoint supports the optional limit, offset and groups parameter:

limit  - How many list items to return
offset - Offset in the dataset
groups - If set then group information are included in the result
         (depending on the result size this can be an expensive call)

The total number of entries in the result is returned in the X-Total-Count header. A request url which runs a new query should be of the following form:

/query/<partition>?q=<query>

/query/<partition>?rid=<result id>

The return data is a result object:

{
    header  : {
        labels       : All column labels of the search result.
        format       : All column format definitions of the search result.
        data         : The data which is displayed in each column of the search result.
                       (e.g. 1:n:name - Name of starting nodes,
                             3:e:key  - Key of edge traversed in the second traversal)
        primary_kind : The primary kind of the search result.
    },
    rows             : [ [ <col0>, <col1>, ... ] ],
    sources          : [ [ <src col0>, <src col1>, ... ] ],
    selections       : [ <row selected> ],
    total_selections : <number of total selections>
    groups           : [ [ <groups of row0> ], [ <groups of row1> ] ... ]
}

Query result endpoint

/queryresult

The query result endpoint is used to run operations on query results.

The quickfilter endpoint (GET) is used to determine the most frequent used values in a particular result column.

/queryresult/<rid>/quickfilter/<column>?limit=<max result items>

The optional limit parameter can be used to limit the result items. The return data is a simple object:

{
    values      : [ <value1>, ... ],
    frequencies : [ <frequency1>, ... ]
}

/queryresult/<rid>/select

The select endpoint (GET) returns the (primary) nodes which are currently selected. The primary node of each row is usually the node from which the query started, when constructing the row of the result (unless the primary keyword was used). The return data is a simple object:

{
    keys   : [ <key of selected node1>, ... ],
    kinds  : [ <kind of selected node1>, ... ]
}

/queryresult/<rid>/select/<row>

The select endpoint with the row parameter (PUT) is used to select single or multiple rows of a query result. The row parameter can either be a positive number or 'all', 'none' or 'invert'. Returns the new number of total selections.

/queryresult/<rid>/groupselected

The groupselected endpoint returns the groups which contain the selected (primary) nodes based on the currently selected rows. The primary node of each row is usually the node from which the query started, when constructing the row of the result (unless the primary keyword was used). The return data is a simple object:

{
    groups : [ <group1>, ... ],
    keys   : [ [ <keys of selected nodes in group1> ], ... ],
	kinds  : [ [ <kinds of selected nodes in group1> ], ... ]
}

The state can be set by sending it to the endpoint via a POST request.

/queryresult/<rid>/groupselected/<name>

The groupselected endpoint with a group name adds (PUT) or removes (DELETE) all selected nodes to/from the given (existing) group.

/queryresult/<rid>/csv

The csv endpoint returns the search result as CSV string.

Index

• Constants
• Variables
• func BlobEndpointInst() api.RestEndpointHandler
• func ClusterEndpointInst() api.RestEndpointHandler
• func ECALEndpointInst() api.RestEndpointHandler
• func ECALSockEndpointInst() api.RestEndpointHandler
• func EqlEndpointInst() api.RestEndpointHandler
• func FindEndpointInst() api.RestEndpointHandler
• func GraphEndpointInst() api.RestEndpointHandler
• func GraphQLEndpointInst() api.RestEndpointHandler
• func GraphQLQueryEndpointInst() api.RestEndpointHandler
• func GraphQLSubscriptionsEndpointInst() api.RestEndpointHandler
• func IndexEndpointInst() api.RestEndpointHandler
• func InfoEndpointInst() api.RestEndpointHandler
• func QueryEndpointInst() api.RestEndpointHandler
• func QueryResultEndpointInst() api.RestEndpointHandler
• type APISearchResult
  • func (r *APISearchResult) AllSelection()
  • func (r *APISearchResult) GetPrimaryNodeColumn() (int, error)
  • func (r *APISearchResult) InvertSelection()
  • func (r *APISearchResult) NoneSelection()
  • func (r *APISearchResult) Selections() []bool
  • func (r *APISearchResult) SetSelection(line int, selection bool)

Constants

const APIv1 = "/v1"

APIv1 is the directory for version 1 of the API

const EndpointBlob = api.APIRoot + APIv1 + "/blob/"

EndpointBlob is the blob endpoint URL (rooted). Handles everything under blob/...

const EndpointClusterQuery = api.APIRoot + APIv1 + "/cluster/"

EndpointClusterQuery is the cluster endpoint URL (rooted). Handles everything under cluster/...

const EndpointECALInternal = api.APIRoot + "/ecal/"

EndpointECALInternal is the ECAL endpoint URL (rooted) for internal operations. Handles everything under ecal/...

const EndpointECALPublic = api.APIRoot + "/api/"

EndpointECALPublic is the ECAL endpoint URL (rooted) for public API operations. Handles everything under api/...

const EndpointECALSock = api.APIRoot + "/sock/"

EndpointECALSock is the ECAL endpoint URL (rooted) for websocket operations. Handles everything under sock/...

const EndpointEql = api.APIRoot + APIv1 + "/eql/"

EndpointEql is the eql endpoint URL (rooted). Handles everything under eql/...

const EndpointFindQuery = api.APIRoot + APIv1 + "/find/"

EndpointFindQuery is the find endpoint URL (rooted). Handles everything under find/...

const EndpointGraph = api.APIRoot + APIv1 + "/graph/"

EndpointGraph is the graph endpoint URL (rooted). Handles everything under graph/...

const EndpointGraphQL = api.APIRoot + APIv1 + "/graphql/"

EndpointGraphQL is the GraphQL endpoint URL (rooted). Handles everything under graphql/...

const EndpointGraphQLQuery = api.APIRoot + APIv1 + "/graphql-query/"

EndpointGraphQLQuery is a query-only GraphQL endpoint URL (rooted). Handles everything under graphql-query/...

const EndpointGraphQLSubscriptions = api.APIRoot + APIv1 + "/graphql-subscriptions/"

EndpointGraphQLSubscriptions is the GraphQL endpoint URL for subscriptions (rooted). Handles websockets under graphql-subscriptions/

const EndpointIndexQuery = api.APIRoot + APIv1 + "/index/"

EndpointIndexQuery is the index endpoint URL (rooted). Handles everything under index/...

const EndpointInfoQuery = api.APIRoot + APIv1 + "/info/"

EndpointInfoQuery is the info endpoint URL (rooted). Handles everything under info/...

const EndpointQuery = api.APIRoot + APIv1 + "/query/"

EndpointQuery is the query endpoint URL (rooted). Handles everything under query/...

const EndpointQueryResult = api.APIRoot + APIv1 + "/queryresult/"

EndpointQueryResult is the query result endpoint URL (rooted). Handles everything under queryresult/...

const HTTPHeaderCacheID = "X-Cache-Id"

HTTPHeaderCacheID is a special header value containing a cache ID for a quick follow up query.

const HTTPHeaderTotalCount = "X-Total-Count"

HTTPHeaderTotalCount is a special header value containing the total count of objects.

const StorageSuffixBlob = ".blob"

StorageSuffixBlob is the suffix for binary blob storage

Variables

var ResultCache *datautil.MapCache

ResultCache is a cache for result sets (by default no expiry and no limit)

var ResultCacheMaxAge int64

ResultCacheMaxAge is the maximum age a result cache entry can have in seconds

var ResultCacheMaxSize uint64

ResultCacheMaxSize is the maximum size for the result cache

var V1EndpointMap = map[string]api.RestEndpointInst{
	EndpointBlob:                 BlobEndpointInst,
	EndpointClusterQuery:         ClusterEndpointInst,
	EndpointEql:                  EqlEndpointInst,
	EndpointGraph:                GraphEndpointInst,
	EndpointGraphQL:              GraphQLEndpointInst,
	EndpointGraphQLQuery:         GraphQLQueryEndpointInst,
	EndpointGraphQLSubscriptions: GraphQLSubscriptionsEndpointInst,
	EndpointIndexQuery:           IndexEndpointInst,
	EndpointFindQuery:            FindEndpointInst,
	EndpointInfoQuery:            InfoEndpointInst,
	EndpointQuery:                QueryEndpointInst,
	EndpointQueryResult:          QueryResultEndpointInst,
	EndpointECALInternal:         ECALEndpointInst,
	EndpointECALSock:             ECALSockEndpointInst,
}

V1EndpointMap is a map of urls to endpoints for version 1 of the API

var V1PublicEndpointMap = map[string]api.RestEndpointInst{
	EndpointECALPublic: ECALEndpointInst,
}

V1PublicEndpointMap is a map of urls to public endpoints for version 1 of the API

Functions

func BlobEndpointInst

func BlobEndpointInst() api.RestEndpointHandler

BlobEndpointInst creates a new endpoint handler.

func ClusterEndpointInst

func ClusterEndpointInst() api.RestEndpointHandler

ClusterEndpointInst creates a new endpoint handler.

func ECALEndpointInst

func ECALEndpointInst() api.RestEndpointHandler

ECALEndpointInst creates a new endpoint handler.

func ECALSockEndpointInst

func ECALSockEndpointInst() api.RestEndpointHandler

ECALSockEndpointInst creates a new endpoint handler.

func EqlEndpointInst

func EqlEndpointInst() api.RestEndpointHandler

EqlEndpointInst creates a new endpoint handler.

func FindEndpointInst

func FindEndpointInst() api.RestEndpointHandler

FindEndpointInst creates a new endpoint handler.

func GraphEndpointInst

func GraphEndpointInst() api.RestEndpointHandler

GraphEndpointInst creates a new endpoint handler.

func GraphQLEndpointInst

func GraphQLEndpointInst() api.RestEndpointHandler

GraphQLEndpointInst creates a new endpoint handler.

func GraphQLQueryEndpointInst

func GraphQLQueryEndpointInst() api.RestEndpointHandler

GraphQLQueryEndpointInst creates a new endpoint handler.

func GraphQLSubscriptionsEndpointInst

func GraphQLSubscriptionsEndpointInst() api.RestEndpointHandler

GraphQLSubscriptionsEndpointInst creates a new endpoint handler.

func IndexEndpointInst

func IndexEndpointInst() api.RestEndpointHandler

IndexEndpointInst creates a new endpoint handler.

func InfoEndpointInst

func InfoEndpointInst() api.RestEndpointHandler

InfoEndpointInst creates a new endpoint handler.

func QueryEndpointInst

func QueryEndpointInst() api.RestEndpointHandler

QueryEndpointInst creates a new endpoint handler.

func QueryResultEndpointInst

func QueryResultEndpointInst() api.RestEndpointHandler

QueryResultEndpointInst creates a new endpoint handler.

Types

type APISearchResult

type APISearchResult struct {
	eql.SearchResult // Normal eql search result
	// contains filtered or unexported fields
}

APISearchResult is a search result maintained by the API. It embeds

func (*APISearchResult) AllSelection

func (r *APISearchResult) AllSelection()

AllSelection selects all rows.

func (*APISearchResult) GetPrimaryNodeColumn

func (r *APISearchResult) GetPrimaryNodeColumn() (int, error)

GetPrimaryNodeColumn determines the first primary node column.

func (*APISearchResult) InvertSelection

func (r *APISearchResult) InvertSelection()

InvertSelection inverts the current selection.

func (*APISearchResult) NoneSelection

func (r *APISearchResult) NoneSelection()

NoneSelection selects none rows.

func (*APISearchResult) Selections

func (r *APISearchResult) Selections() []bool

Selections returns all current selections.

func (*APISearchResult) SetSelection

func (r *APISearchResult) SetSelection(line int, selection bool)

SetSelection sets a new selection.