Protocol Documentation

Table of Contents

graphik.proto

Top

AggFilter

FieldTypeLabelDescription
filter Filter

aggregate Aggregate

field string

Validated Fields

Field Validations
filter
  • msg_exists: true
field
  • regex: ((^|, )(|^attributes.(.*)))+$

AuthTarget

AuthTarget is the payload/input to Authorizer expressions

FieldTypeLabelDescription
user Doc

user is the user making the request

target google.protobuf.Struct

target is the request/response represented as a Struct

headers AuthTarget.HeadersEntry repeated

headers are the request headers

Validated Fields

Field Validations
user
  • msg_exists: true

AuthTarget.HeadersEntry

FieldTypeLabelDescription
key string

value string

Authorizer

Authorizer is a graph primitive used for authorizing inbound requests and/or responses(see AuthTarget)

FieldTypeLabelDescription
name string

name is the unique name of the authorizer

method string

method is the rpc method that will invoke the authorizer

expression string

expression is the boolean CEL expression that evaluates either the request or response body

target_requests bool

target_responses sets the authorizer to evaluate request bodies

target_responses bool

target_responses sets the authorizer to evaluate response bodies

Validated Fields

Field Validations
name
  • regex: ^.{1,225}$
method
  • regex: ^.{1,225}$
expression
  • regex: ^.{1,225}$

Authorizers

Authorizers is an array of authorizer

FieldTypeLabelDescription
authorizers Authorizer repeated

Boolean

Boolean is a simple boolean value

FieldTypeLabelDescription
value bool

ConnectFilter

ConnectFilter is used to fetch connections related to a single noted

FieldTypeLabelDescription
doc_ref Ref

doc_ref is the ref to the target doc. (validator.field) = {msg_exists : true}]

gtype string

gtype is the type of connections to return. (validator.field) = {regex : "^.{1,225}$"}

expression string

expression is a CEL expression used to filter connections/modes

limit uint64

limit is the maximum number of items to return. (validator.field) = {int_gt : 0}

sort string

custom sorting of the results. (validator.field) = {regex : "((^|, )(|ref.gid|ref.gtype|^attributes.(.*)))+$"}

seek string

seek to a specific key for pagination

reverse bool

reverse the results

Validated Fields

Field Validations
doc_ref
  • msg_exists: true
gtype
  • regex: ^.{1,225}$
limit
  • int_gt: 0
sort
  • regex: ((^|, )(|ref.gid|ref.gtype|^attributes.(.*)))+$

Connection

Connection is a graph primitive that represents a relationship between two docs

FieldTypeLabelDescription
ref Ref

ref is the ref to the connection

attributes google.protobuf.Struct

attributes are k/v pairs

directed bool

directed is false if the connection is bi-directional

from Ref

from is the doc ref that is the source of the connection

to Ref

to is the doc ref that is the destination of the connection

Validated Fields

Field Validations
ref
  • msg_exists: true
from
  • msg_exists: true
to
  • msg_exists: true

ConnectionConstructor

ConnectionConstructor is used to create an Connection

FieldTypeLabelDescription
ref RefConstructor

ref is the ref to the new Connection. If an id isn't present, one will be generated.

attributes google.protobuf.Struct

attributes are k/v pairs

directed bool

directed is false if the connection is bi-directional

from Ref

from is the doc ref that is the root of the connection

to Ref

to is the doc ref that is the destination of the connection

Validated Fields

Field Validations
ref
  • msg_exists: true
from
  • msg_exists: true
to
  • msg_exists: true

ConnectionConstructors

ConnectionConstructors is an array of ConnectionConstructor

FieldTypeLabelDescription
connections ConnectionConstructor repeated

Connections

Connections is an array of Connection

FieldTypeLabelDescription
connections Connection repeated

seek_next string

Constraint

Constraint a graph primitive used to validate custom doc/connection constraints

FieldTypeLabelDescription
name string

gtype string

expression string

target_docs bool

if target_docs is true, this validator will be applied to documents.

target_connections bool

if target_connections is true, this validator will be applied to connections.

Validated Fields

Field Validations
name
  • regex: ^.{1,225}$
gtype
  • regex: ^.{1,225}$
expression
  • regex: ^.{1,225}$

Constraints

FieldTypeLabelDescription
constraints Constraint repeated

Doc

Doc is a Graph primitive representing a single entity/resource. It is connected to other docs via Connections

FieldTypeLabelDescription
ref Ref

ref is the ref to the doc

attributes google.protobuf.Struct

k/v pairs

Validated Fields

Field Validations
ref
  • msg_exists: true

DocConstructor

DocConstructor is used to create a doc

FieldTypeLabelDescription
ref RefConstructor

ref is the ref to the new Doc. If an id isn't present, one will be generated.

attributes google.protobuf.Struct

arbitrary k/v pairs

Validated Fields

Field Validations
ref
  • msg_exists: true

DocConstructors

DocConstructor is used to create a batch of docs

FieldTypeLabelDescription
docs DocConstructor repeated

docs is an array of doc constructors

Docs

Docs is an array of docs

FieldTypeLabelDescription
docs Doc repeated

docs is an array of docs

seek_next string

Edit

Edit patches the attributes of a Doc or Connection

FieldTypeLabelDescription
ref Ref

ref is the ref to the target doc/connection to patch

attributes google.protobuf.Struct

attributes are k/v pairs used to overwrite k/v pairs on a doc/connection

Validated Fields

Field Validations
ref
  • msg_exists: true

EditFilter

EditFilter is used to patch/edit docs/connections

FieldTypeLabelDescription
filter Filter

filter is used to filter docs/connections to patch

attributes google.protobuf.Struct

attributes are k/v pairs used to overwrite k/v pairs on all docs/connections that pass the filter

ExistsFilter

ExistsFilter is used as input into all Exists(boolean) related queries.

FieldTypeLabelDescription
gtype string

expression string

seek string

seek to a specific key for pagination

reverse bool

reverse the results

index string

search in a specific index

Validated Fields

Field Validations
gtype
  • regex: ^.{1,225}$
expression
  • regex: ^.{1,225}$

ExprFilter

FieldTypeLabelDescription
expression string

expression is a CEL expression used to filter connections/nodes

Filter

Filter is a generic filter using Common Expression Language

FieldTypeLabelDescription
gtype string

gtype is the doc/connection type to be filtered

expression string

expression is a CEL expression used to filter connections/modes

limit uint64

limit is the maximum number of items to return

sort string

custom sorting of the results.

seek string

seek to a specific key for pagination

reverse bool

reverse the results

index string

search in a specific index

Validated Fields

Field Validations
gtype
  • regex: ^.{1,225}$
limit
  • int_gt: 0
sort
  • regex: ((^|, )(|ref.gid|ref.gtype|^attributes.(.*)))+$

Flags

FieldTypeLabelDescription
open_id_discovery string

open id connect discovery uri ex: https://accounts.google.com/.well-known/openid-configuration (env: GRAPHIK_OPEN_ID)

storage_path string

persistant storage ref (env: GRAPHIK_STORAGE_PATH)

allow_headers string repeated

cors allow headers (env: GRAPHIK_ALLOW_HEADERS)

allow_methods string repeated

cors allow methods (env: GRAPHIK_ALLOW_METHODS)

allow_origins string repeated

cors allow origins (env: GRAPHIK_ALLOW_ORIGINS)

root_users string repeated

root user is a list of email addresses that bypass authorizers. (env: GRAPHIK_ROOT_USERS)

tls_cert string

tls_key string

require_request_authorizers bool

require_response_authorizers bool

join_raft string

raft_peer_id string

listen_port int64

raft_secret string

debug bool

environment string

raft_advertise string

raft_max_pool int64

mutual_tls bool

ca_cert string

Graph

Graph is an array of docs and connections

FieldTypeLabelDescription
docs Docs

docs are docs present in the graph

connections Connections

connections are connections present in the graph

Index

Index is a secondary index

FieldTypeLabelDescription
name string

gtype string

gtype is the doc/connection type to be filtered

expression string

expression is a CEL expression used to filter connections/modes

target_docs bool

if target_docs is true, this index will be applied to documents.

target_connections bool

if target_connections is true, this index will be applied to connections.

Validated Fields

Field Validations
name
  • regex: ^.{1,225}$
gtype
  • regex: ^.{1,225}$
expression
  • regex: ^.{1,225}$

IndexConstructor

IndexConstructor is used to construct Indexes

FieldTypeLabelDescription
name string

name is the unique name of the Index

gtype string

gtype is the doc/connection type to be filtered

expression string

expression is a CEL expression used to filter connections/modes

target_docs bool

if target_docs is true, this index will be applied to documents.

target_connections bool

if target_connections is true, this index will be applied to connections.

Validated Fields

Field Validations
name
  • regex: ^.{1,225}$
gtype
  • regex: ^.{1,225}$
expression
  • regex: ^.{1,225}$

Indexes

Indexes is an array of Index

FieldTypeLabelDescription
indexes Index repeated

Message

Message is received on PubSub subscriptions

FieldTypeLabelDescription
channel string

channel is the channel the message was sent to

data google.protobuf.Struct

data is the data sent with the message

user Ref

user is the sender that triggered/sent the message

timestamp google.protobuf.Timestamp

timestamp is when the message was sent

method string

Validated Fields

Field Validations
channel
  • regex: ^.{1,225}$
data
  • msg_exists: true
user
  • msg_exists: true
timestamp
  • msg_exists: true
method
  • regex: ^.{1,225}$

Number

Number is a simple double/float64 value

FieldTypeLabelDescription
value double

OutboundMessage

OutboundMessage is a message to be published to a pubsub channel

FieldTypeLabelDescription
channel string

channel is the target channel to send the message to

data google.protobuf.Struct

data is the data to send with the message

Validated Fields

Field Validations
channel
  • regex: ^.{1,225}$
data
  • msg_exists: true

Peer

FieldTypeLabelDescription
node_id string

addr string

Pong

Pong returns PONG if the server is healthy

FieldTypeLabelDescription
message string

message returns PONG if healthy

RaftCommand

FieldTypeLabelDescription
user Doc

method string

set_docs Doc repeated

set_connections Connection repeated

del_docs Ref repeated

del_connections Ref repeated

set_indexes Indexes

set_authorizers Authorizers

set_constraints Constraints

send_message Message

set_triggers Triggers

RaftState

FieldTypeLabelDescription
leader string

membership Membership

peers Peer repeated

stats RaftState.StatsEntry repeated

RaftState.StatsEntry

FieldTypeLabelDescription
key string

value string

Ref

Ref describes a doc/connection type & id

FieldTypeLabelDescription
gtype string

gtype is the type of the doc/connection ex: pet

gid string

gid is the unique id of the doc/connection within the context of it's type

Validated Fields

Field Validations
gtype
  • regex: ^.{1,225}$
gid
  • regex: ^.{1,225}$

RefConstructor

RefConstructor creates a new Ref

FieldTypeLabelDescription
gtype string

gtype is the type of the doc/connection ex: pet

gid string

gid is the unique id of the doc/connection within the context of it's type

Validated Fields

Field Validations
gtype
  • regex: ^.{1,225}$

Refs

Refs is an array of refs

FieldTypeLabelDescription
refs Ref repeated

Schema

Schema returns registered connection & doc types

FieldTypeLabelDescription
connection_types string repeated

connection_types are the types of connections in the graph

doc_types string repeated

doc_types are the types of docs in the graph

authorizers Authorizers

constraints Constraints

indexes Indexes

triggers Triggers

SearchConnectFilter

FieldTypeLabelDescription
filter Filter

gtype string

attributes google.protobuf.Struct

attributes are k/v pairs

directed bool

directed is false if the connection is bi-directional

from Ref

from is the doc ref that is the root of the connection

Validated Fields

Field Validations
from
  • msg_exists: true

SearchConnectMeFilter

FieldTypeLabelDescription
filter Filter

gtype string

attributes google.protobuf.Struct

attributes are k/v pairs

directed bool

directed is false if the connection is bi-directional

StreamFilter

StreamFilter is used to filter messages in a pubsub channel

FieldTypeLabelDescription
channel string

channel is the target channel to filter from

expression string

expression is CEL expression used to filter messages

min google.protobuf.Timestamp

minimum message timestamp to stream (optional)

max google.protobuf.Timestamp

maximum message timestamp to stream (optional)

Validated Fields

Field Validations
channel
  • regex: ^.{1,225}$

Traversal

FieldTypeLabelDescription
doc Doc

traversal_path Ref repeated

depth uint64

hops uint64

Traversals

FieldTypeLabelDescription
traversals Traversal repeated

TraverseFilter

FieldTypeLabelDescription
root Ref

doc_expression string

connection_expression string

limit uint64

sort string

custom sorting of the results. (validator.field) = {regex : "((^|, )(|ref.gid|ref.gtype|^attributes.(.*)))+$"}

reverse bool

algorithm Algorithm

max_depth uint64

maximum degree/depth of nodes to be visited during traversal

max_hops uint64

maximum number of nodes to be visited during traversal

Validated Fields

Field Validations
root
  • msg_exists: true
limit
  • int_gt: 0
sort
  • regex: ((^|, )(|ref.gid|ref.gtype|^attributes.(.*)))+$
max_depth
  • int_gt: 0
max_hops
  • int_gt: 0

TraverseMeFilter

FieldTypeLabelDescription
doc_expression string

connection_expression string

limit uint64

sort string

custom sorting of the results. (validator.field) = {regex : "((^|, )(|ref.gid|ref.gtype|^attributes.(.*)))+$"}

reverse bool

algorithm Algorithm

max_depth uint64

maximum degree/depth of nodes to be visited during traversal

max_hops uint64

maximum number of nodes to be visited during traversal

Validated Fields

Field Validations
limit
  • int_gt: 0
sort
  • regex: ((^|, )(|ref.gid|ref.gtype|^attributes.(.*)))+$
max_depth
  • int_gt: 0
max_hops
  • int_gt: 0

Trigger

Trigger may be used to automatically mutate the attributes of documents/connections before they are commited to the database

FieldTypeLabelDescription
name string

name is the unique name of the authorizer

gtype string

gtype is the type of doc/connection will invoke the trigger

trigger string

trigger is the arrow syntax expression that mutates the doc/connection before it is stored ref: https://github.com/graphikDB/trigger

target_docs bool

if target_docs is true, this trigger will be applied to documents.

target_connections bool

if target_connections is true, this trigger will be applied to connections.

Validated Fields

Field Validations
name
  • regex: ^.{1,225}$
gtype
  • regex: ^.{1,225}$
trigger
  • regex: ^.{1,225}$

Triggers

Triggers is an array of Trigger

FieldTypeLabelDescription
triggers Trigger repeated

Aggregate

NameNumberDescription
COUNT 0

SUM 1

AVG 2

MAX 3

MIN 4

PROD 5

Algorithm

NameNumberDescription
BFS 0

BFS is short for the breadth-first search algorithm

DFS 1

DFS is short for the depth-first search algorithm

Membership

NameNumberDescription
UNKNOWN 0

FOLLOWER 1

CANDIDATE 2

LEADER 3

SHUTDOWN 4

DatabaseService

DatabaseService is the primary database service

Method NameRequest TypeResponse TypeDescription
GetSchema .google.protobuf.Empty Schema

GetSchema gets schema about the Graph doc & connection types

SetAuthorizers Authorizers .google.protobuf.Empty

SetAuthorizers sets all of the authorizers in the graph database

SetIndexes Indexes .google.protobuf.Empty

SetIndexes sets all of the indexes in the graph database

SetConstraints Constraints .google.protobuf.Empty

SetConstraints sets all of the constraints in the graph database

SetTriggers Triggers .google.protobuf.Empty

SetTriggers sets all of the triggers in the graph database

Me .google.protobuf.Empty Doc

Me returns a Doc of the currently logged in user

CreateDoc DocConstructor Doc

CreateDoc creates a doc in the graph

CreateDocs DocConstructors Docs

CreateDocs creates a batch of docs in the graph

PutDoc Doc Doc

PutDoc create-or-replaces a Doc in the graph

PutDocs Docs Docs

PutDocs puts a batch of docs in the graph

GetDoc Ref Doc

GetDoc gets a single doc in the graph

SearchDocs Filter Docs

SearchDocs searches the graph for docs

Traverse TraverseFilter Traversals

Traverse executes a depth first search of the graph for docs

TraverseMe TraverseMeFilter Traversals

TraverseMe executes a graph traversal searching for docs related to the currently logged in user

EditDoc Edit Doc

EditDoc patches/edits a docs attributes

EditDocs EditFilter Docs

EditDocs patches a batch of docs attributes that pass the patch filter

DelDoc Ref .google.protobuf.Empty

DelDoc deletes a doc & all of it's connected connections

DelDocs Filter .google.protobuf.Empty

DelDocs deletes a batch of docs that pass the filter

ExistsDoc ExistsFilter Boolean

ExistsDoc searches for a Doc and returns a Boolean indicating if it exists in the graph

ExistsConnection ExistsFilter Boolean

ExistsConnection searches for a Connection and returns a Boolean indicating if it exists in the graph

HasDoc Ref Boolean

HasDoc searches for the Doc by Ref returns a Boolean indicating if it exists in the graph

HasConnection Ref Boolean

HasConnection searches for the Connection by Ref returns a Boolean indicating if it exists in the graph

CreateConnection ConnectionConstructor Connection

CreateConnection creates an connection in the graph

CreateConnections ConnectionConstructors Connections

CreateConnections creates a batch of connections in the graph

PutConnection Connection Connection

PutConnection create-or-replaces a Connection in the graph

PutConnections Connections Connections

PutConnections puts a batch of connections in the graph

SearchAndConnect SearchConnectFilter Connections

searches for documents and forms connections based on whether they pass a filter

SearchAndConnectMe SearchConnectMeFilter Connections

SearchAndConnectMe searches for documents and forms connections from the origin user to the document based on whether they pass a filter

GetConnection Ref Connection

GetConnection gets a single connection in the graph

SearchConnections Filter Connections

SearchConnections searches the graph for connections

EditConnection Edit Connection

EditConnection patches an connections attributes

EditConnections EditFilter Connections

EditConnections patches a batch of connections attributes that pass the patch filter

DelConnection Ref .google.protobuf.Empty

DelConnection deletes an connection from the graph

DelConnections Filter .google.protobuf.Empty

DelConnections deletes a batch of connections that pass the filter

ConnectionsFrom ConnectFilter Connections

ConnectionsFrom returns connections that source from the given doc ref that pass the filter

ConnectionsTo ConnectFilter Connections

ConnectionsTo returns connections that point to the given doc ref that pass the filter

AggregateDocs AggFilter Number

AggregateDocs executes an aggregation function against the graph

AggregateConnections AggFilter Number

Broadcast OutboundMessage .google.protobuf.Empty

Broadcast broadcasts a message to a pubsub channel

Stream StreamFilter Message stream

Stream subscribes to messages on a pubsub channel

PushDocConstructors DocConstructor stream Doc stream

PushDocConstructors streams DocConstructor to the server, creating them as they're sent and streaming the new doc to the client

PushConnectionConstructors ConnectionConstructor stream Connection stream

PushConnectionConstructors streams ConnectionConstructor to the server, creating them as they're sent and streaming the new connection to the client

SeedDocs Doc stream .google.protobuf.Empty

SeedConnections Connection stream .google.protobuf.Empty

RaftService

Method NameRequest TypeResponse TypeDescription
Ping .google.protobuf.Empty Pong

Ping returns PONG if the server is health

JoinCluster Peer .google.protobuf.Empty

ClusterState .google.protobuf.Empty RaftState

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)