schema.graphql

# time is an rfc 3339 timestamp
scalar Time
# Map is a k/v map where the key is a string and the value is any value
scalar Map
# Empty is a container to represent no values
scalar Empty

# Algorithm is a Graph Traversal algorithm
enum Algorithm {
  # BFS is short for the breadth-first search algorithm
  BFS
  # DFS is short for the depth-first search algorithm
  DFS
}

enum Aggregate {
  # Count counts the number of elements in the group defined
  COUNT
  # SUM calculates the sum of the given attribute/expression in the group defined
  SUM
  # AVG calculates the average value of the given attribute/expression in the group defined
  AVG
  # MAX finds the maximum in the group defined
  MAX
  # MIN finds the minimum in the group defined
  MIN
  # PROD finds the product of all of the values in the group defined
  PROD
}

# Membership is the state of a raft membership in a cluster
enum Membership {
  UNKNOWN
  FOLLOWER
  CANDIDATE
  LEADER
  SHUTDOWN
}

# Ref describes a doc/connection type & id
type Ref {
  # gtype is the type of the doc/connection ex: pet
  gtype: String!
  # gid is the unique id of the doc/connection within the context of it's type
  gid: String!
}

# Doc is a Graph primitive representing a single entity/resource. It is connected to other docs via Connections
type Doc {
  # ref is the ref to the doc
  ref: Ref!
  # k/v pairs
  attributes: Map
}

# Docs is an array of docs
type Docs {
  # docs is an array of docs
  docs: [Doc!]
  # seek_next is the next value in the sequence (used for pagination)
  seek_next: String
}

# Traversal is a document found during a traversal & its relative path to the root node that searched for it
type Traversal {
  doc: Doc!
  traversal_path: [Ref!]
  depth: Int!
  hops: Int!
}

# AuthTarget is the payload/input to Authorizer expressions
type AuthTarget {
  # user is the user making the request
  user: Doc!
  # target is the request/response represented as a Map
  target: Map!
  # headers are the request headers
  headers: Map!
}

# Traversals is an array of Traversal that is returned from Graph traversal algorithms
type Traversals {
  # traversals is an array of Traversal
  traversals: [Traversal!]
}

# Refs is an array of Ref
type Refs {
  refs: [Ref!]
}

# Constraint a graph primitive used to validate custom doc/connection constraints
type Constraint {
  # name is the unique name of the constraint
  name: String!
  # gtype is the type of object the constraint will be applied to (ex: user)
  gtype: String!
  # expression is a boolean CEL expression used to evaluate the doc/connection
  expression: String!
  # if target_docs is true, this constraint will be applied to documents.
  target_docs: Boolean!
  # if target_connections is true, this constraint will be applied to connections.
  target_connections: Boolean!
}

# Constraints is an array of Constraint
type Constraints {
  constraints: [Constraint!]
}

# triggers may be used to automatically mutate the attributes of documents/connections before they are commited to the database
type Trigger {
  # name is the unique name of the constraint
  name: String!
  # gtype is the type of object the constraint will be applied to (ex: user)
  gtype: String!
  # trigger is the arrow syntax expression that mutates the doc/connection before it is stored ref: https://github.com/graphikDB/trigger
  trigger: String!
  # if target_docs is true, this constraint will be applied to documents.
  target_docs: Boolean!
  # if target_connections is true, this constraint will be applied to connections.
  target_connections: Boolean!
}

# Triggers is an array of Trigger
type Triggers {
  triggers: [Trigger!]
}

# Connection is a graph primitive that represents a relationship between two docs
type Connection {
  # ref is the ref to the connection
  ref: Ref!
  # k/v pairs
  attributes: Map
  # directed is false if the connection is bi-directional
  directed: Boolean!
  # from is the doc ref that is the source of the connection
  from: Ref!
  # to is the doc ref that is the destination of the connection
  to: Ref!
}

# Connections is an array of connections
type Connections {
  # connections is an array of connections
  connections: [Connection!]
  # seek_next is the next value in the sequence (used for pagination)
  seek_next: String
}

# Index is a graph primitive used for fast lookups of docs/connections that pass a boolean CEL expression
type Index {
  # name is the unique name of the index in the graph
  name: String!
  # gtype is the type of object the index will be applied to (ex: user)
  gtype: String!
  # expression is a boolean CEL expression used to evaluate the doc/connection
  expression: String!
  # if target_docs is true, this index will be applied to documents.
  target_docs: Boolean!
  # if target_connections is true, this index will be applied to connections.
  target_connections: Boolean!
}

# Indexes is an array of Index
type Indexes {
  indexes: [Index!]
}

# Peer is the address and id of a node in the raft cluster
type Peer {
  node_id: String!
  addr: String!
}

# RaftState returns information about the raft cluster
type RaftState {
  leader: String!
  membership: Membership!
  peers: [Peer!]
  stats: Map!
}

# Authorizer is a graph primitive used for authorizing inbound requests and/or responses(see AuthTarget)
type Authorizer {
  # name is the unique name of the authorizer in the graph
  name: String!
  # method is the rpc method that will invoke the authorizer
  method: String!
  # expression is the boolean CEL expression that evaluates either the request or response body
  expression: String!
  # target_responses sets the authorizer to evaluate request bodies of the target grpc method
  target_requests:   Boolean!
  # target_responses sets the authorizer to evaluate response bodies of the target grpc method
  target_responses: Boolean!
}

# Authorizers is an array of Authorizer
type Authorizers {
  authorizers: [Authorizer!]
}

# Schema returns registered connection & doc types & other graph primitives
type Schema {
  # connection_types are the types of connections in the graph
  connection_types: [String!]
  # doc_types are the types of docs in the graph
  doc_types: [String!]
  # authorizers are all of registered authorizers in the graph
  authorizers: Authorizers
  # constraints are all of registered constraints in the graph
  constraints: Constraints
  # indexes are all of the registered indexes in the graph
  indexes: Indexes
  # triggers are all of the registered triggers in the graph
  triggers: Triggers
}

# Message is received on PubSub subscriptions
type Message {
  # channel is the channel the message was sent to
  channel: String!
  # data is the data sent with the message
  data: Map!
  # user is the user that sent/triggered the message
  user: Ref!
  # timestamp is when the message was sent
  timestamp: Time!
  # method is the gRPC method that invoked the message delivery
  method: String!
}

# RefConstructor is used to create a Ref
input RefConstructor {
  # gtype is the type of the doc/connection ex: pet
  gtype: String!
  # gid is the unique id of the doc/connection within the context of it's type. If none is provided, a k-sortable uuid will be assigned
  gid: String
}

# DocConstructor is used to create a Doc
input DocConstructor {
  # ref is the gtype/gid of the doc to create. If no gid is provided, a k-sortable uuid will be assigned
  ref: RefConstructor!
  # attributes are k/v pairs
  attributes: Map
}

# DocConstructors is an array of DocConstructor
input DocConstructors {
  docs: [DocConstructor!]!
}

# ConnectionConstructor is used to create an Connection
input ConnectionConstructor {
  # ref is the gtype/gid of the connection to create. If no gid is provided, a k-sortable uuid will be assigned
  ref: RefConstructor!
  # directed is false if the connection is bi-directional
  directed: Boolean!
  # attributes are k/v paris associated with the Connection to create
  attributes: Map
  # from is the doc ref that is the source of the connection
  from: RefInput!
  # to is the doc ref that is the destination of the connection
  to: RefInput!
}

# ConnectionConstructors is an array of ConnectionConstructor
input ConnectionConstructors {
  connections: [ConnectionConstructor!]!
}

# RefInput is the ref to a doc/connection
input RefInput {
  # ref is the ref to the target doc/connection to edit
  gtype: String!
  # ref is the ref to the target doc/connection to edit
  gid: String!
}

# PeerInput is the address and id of a node in the raft cluster
input PeerInput {
  node_id: String!
  addr: String!
}

# Filter is a generic filter using Common Expression Language
input Filter {
  # gtype is the doc/connection type to be filtered
  gtype: String!
  # expression is a CEL expression used to filter connections/nodes
  expression: String
  # limit is the maximum number of items to return
  limit: Int!
  # custom sorting of the results.
  sort: String
  # seek to a specific key for pagination
  seek: String
  # reverse the results
  reverse: Boolean
  # search in a specific index
  index: String
}

# SearchConnectFilter is used for searching for documents and adding connections based on whether they pass a Filter
input SearchConnectFilter {
  # filter is the filter to apply against the graph.
  filter: Filter!
  # gtype is the type of the connection to create
  gtype: String!
  # attributes are k/v pairs to associate with the new connection
  attributes: Map
  # directed indicates whether the connection is uni-directional(instagram) or bi-directional(facebook)
  directed: Boolean!
  # from indicates the root document of the connection to create
  from: RefInput!
}

# SearchConnectMeFilter is used for searching for documents and adding connections from the origin user to the document based on whether they pass a Filter
input SearchConnectMeFilter {
  # filter is the filter to apply against the graph.
  filter: Filter!
  # gtype is the type of the connection to create
  gtype: String!
  # attributes are k/v pairs to associate with the new connection
  attributes: Map
  # directed indicates whether the connection is uni-directional(instagram) or bi-directional(facebook)
  directed: Boolean!
}

# AggFilter is a filter used for aggragation queries
input AggFilter {
  # filter is the filter to apply against the graph.
  filter: Filter!
  # aggregate is the aggregation function to apply against the graph
  aggregate: Aggregate!
  # field is the field to aggregate(ex: attributes.age). The field must be a float/number value
  field: String
}

# TraverseFilter is a filter used for graph traversals
input TraverseFilter {
  # gtype is the doc/connection type to be filtered
  root: RefInput!
  # doc_expression is a boolean CEL expression used to determine which docs to traverse
  doc_expression: String
  # connection_expression is a boolean CEL expression used to determine which connections to traverse
  connection_expression: String
  # limit is the maximum number of items to return
  limit: Int!
  # custom sorting of the results.
  sort: String
  # reverse the direction of the connection traversal
  reverse: Boolean
  # DFS(depth-first-search) or BFS(breadth-first-search). Defaults to breadth-first
  algorithm: Algorithm
  # maximum degree/depth of nodes to be visited during traversal
  max_depth: Int!
  # maximum number of nodes to be visited during traversal
  max_hops: Int!
}

# TraverseMeFilter is a filter used for graph traversals of the origin user
input TraverseMeFilter {
  # doc_expression is a boolean CEL expression used to determine which docs to traverse
  doc_expression: String
  # connection_expression is a boolean CEL expression used to determine which connections to traverse
  connection_expression: String
  # limit is the maximum number of items to return
  limit: Int!
  # custom sorting of the results.
  sort: String
  # reverse the direction of the connection traversal
  reverse: Boolean
  # DFS(depth-first-search) or BFS(breadth-first-search). Defaults to breadth-first
  algorithm: Algorithm
  # maximum degree/depth of nodes to be visited during traversal
  max_depth: Int!
  # maximum number of nodes to be visited during traversal
  max_hops: Int!
}

# ConnectFilter is used to fetch connections related to a single noted
input ConnectFilter {
  # doc_ref is the ref to the target doc
  doc_ref: RefInput!
  # gtype is the type of connections to return
  gtype: String!
  # expression is a CEL expression used to filter connections
  expression: String,
  # limit is the maximum number of connections to return
  limit: Int!
  # custom sorting of the results.
  sort: String
  # seek to a specific key for pagination
  seek: String
  # reverse the results
  reverse: Boolean
}

# StreamFilter is used to filter messages in a pubsub channel
input StreamFilter {
  # channel is the target channel to listen on
  channel: String!
  # expression is a CEL expression used to filter messages
  expression: String
  # minimum message timestamp to stream (optional)
  min: Time
  # maximum message timestamp to stream (optional)
  max: Time
}

# Edit edites the attributes of a Doc or Connection
input Edit {
  # ref is the ref to the target doc/connection to edit
  ref: RefInput!
  # attributes are k/v pairs used to overwrite k/v pairs on a doc/connection
  attributes: Map!
}

# EditFilter is used to edit/patch docs/connections
input EditFilter {
  # filter is used to filter docs/connections to edit
  filter: Filter!
  # attributes are k/v pairs used to overwrite k/v pairs on a doc/connection
  attributes: Map!
}

# OutboundMessage is a message to be published to a pubsub channel
input OutboundMessage {
  # channel is the target channel to send the message to
  channel: String!
  # data is the data to send with the message
  data: Map!
}

# ExprFilter is a generic filter that uses a boolean CEL expression
input ExprFilter {
  # expression is a CEL expression used to filter messages/docs/connections
  expression: String
}

# IndexInput is used to construct Indexes
input IndexInput {
  # name is the unique name of the index in the graph
  name: String!
  # gtype is the type of object the constraint will be applied to (ex: user)
  gtype: String!
  # expression is a boolean CEL expression used to evaluate the doc/connection
  expression: String!
  # if target_docs is true, this index will be applied to documents.
  target_docs: Boolean!
  # if target_connections is true, this index will be applied to connections.
  target_connections: Boolean!
}

# IndexesInput is an array IndexInput
input IndexesInput {
  indexes: [IndexInput!]
}


# TriggerInput is used to construct Trigger
input TriggerInput {
  # name is the unique name of the constraint
  name: String!
  # gtype is the type of object the constraint will be applied to (ex: user)
  gtype: String!
  # trigger is the arrow syntax expression that mutates the doc/connection before it is stored ref: https://github.com/graphikDB/trigger
  trigger: String!
  # if target_docs is true, this constraint will be applied to documents.
  target_docs: Boolean!
  # if target_connections is true, this constraint will be applied to connections.
  target_connections: Boolean!
}

# TriggersInput is an array TriggerInput
input TriggersInput {
  triggers: [TriggerInput!]
}

# AuthorizerInput is used to create a new Authorizer
input AuthorizerInput {
  # name is the unique name of the authorizer in the graph
  name: String!
  # method is the rpc method that will invoke the authorizer
  method: String!
  # expression is the boolean CEL expression that evaluates either the request or response body
  expression: String!
  # target_responses sets the authorizer to evaluate request bodies of the target grpc method
  target_requests:   Boolean!
  # target_responses sets the authorizer to evaluate response bodies of the target grpc method
  target_responses: Boolean!
}

# AuthorizersInput is an array of authorizers
input AuthorizersInput {
  authorizers: [AuthorizerInput!]
}

# ConstraintInput is used to construct a new constraint
input ConstraintInput {
  # name is the unique name of the constraint
  name: String!
  # gtype is the type of object the constraint will be applied to (ex: user)
  gtype: String!
  # expression is a boolean CEL expression used to evaluate the doc/connection
  expression: String!
  # if target_docs is true, this constraint will be applied to documents.
  target_docs: Boolean!
  # if target_connections is true, this constraint will be applied to connections.
  target_connections: Boolean!
}

# ConstraintsInput is an array of ConstraintInput
input ConstraintsInput {
  constraints: [ConstraintInput!]
}

# Exists is a filter used to determine whether a doc/connection exists in the graph
input ExistsFilter {
  # gtype is the doc/connection type to be filtered
  gtype: String!
  # expression is a CEL expression used to filter connections/nodes
  expression: String!
  # seek to a specific key for pagination
  seek: String
  # reverse the results
  reverse: Boolean
  # search in a specific index
  index: String
}

input PutDoc {
  # ref is the ref to the doc
  ref: RefInput!
  # k/v pairs
  attributes: Map
}

input PutDocs {
  # docs is an array of docs
  docs: [PutDoc!]
}

input PutConnection {
  # ref is the ref to the connection
  ref: RefInput!
  # k/v pairs
  attributes: Map
  # directed is false if the connection is bi-directional
  directed: Boolean!
  # from is the doc ref that is the source of the connection
  from: RefInput!
  # to is the doc ref that is the destination of the connection
  to: RefInput!
}

input PutConnections {
  # connections is an array of connections
  connections: [PutConnection!]
}

type Mutation {
  # createDoc creates a single doc in the graph
  createDoc(input: DocConstructor!): Doc!
  # createDocs creates 1-many documents in the graph
  createDocs(input: DocConstructors!): Docs!
  # putDoc create-or-replaces a Doc in the graph
  putDoc(input: PutDoc): Doc!
  # putDocs puts a batch of docs in the graph
  putDocs(input: PutDocs): Docs!
  # editDoc edites a single doc in the graph
  editDoc(input: Edit!): Doc!
  # editDocs edites 0-many docs in the graph
  editDocs(input: EditFilter!): Docs!
  # delDoc deletes a doc by reference
  delDoc(input: RefInput!): Empty
  # delDocs deletes 0-many docs that pass a Filter
  delDocs(input: Filter!): Empty
  # createConnection creates a single connection in the graph
  createConnection(input: ConnectionConstructor!): Connection!
  # createConnections creates 1-many connections in the graph
  createConnections(input: ConnectionConstructors!): Connections!
  # putConnection create-or-replaces a Connection in the graph
  putConnection(input: PutConnection): Connection!
  # putConnections puts a batch of connections in the graph
  putConnections(input: PutConnections): Connections!
  # editConnection edites a single connection in the graph
  editConnection(input: Edit!): Connection!
  # editConnections edites 0-many connections in the graph
  editConnections(input: EditFilter!): Connections!
  # delConnection deletes a connection by reference
  delConnection(input: RefInput!): Empty
  # delConnections deletes 0-many connections that pass a Filter
  delConnections(input: Filter!): Empty
  # broadcast broadcasts a mesage to a pubsub/stream channel
  broadcast(input: OutboundMessage!): Empty
  # setIndexes sets all of the indexes in the graph
  setIndexes(input: IndexesInput!): Empty
  # setAuthorizers sets all of the authorizers in the graph
  setAuthorizers(input: AuthorizersInput!): Empty
  # setConstraints sets all of the constraints in the graph
  setConstraints(input: ConstraintsInput!): Empty
  # v sets all of the triggers in the graph
  setTriggers(input: TriggersInput!): Empty
  # searchAndConnect searches for documents and forms connections based on whether they pass a filter
  searchAndConnect(input: SearchConnectFilter!): Connections!
  # searchAndConnectMe searches for documents and forms connections from the origin user to the document based on whether they pass a filter
  searchAndConnectMe(input: SearchConnectMeFilter!): Connections!
}

type Query {
  # getSchema gets information about node/connection types, type-constraints, indexes, and authorizers
  getSchema(where: Empty): Schema!
  # me returns a Doc of the currently logged in user
  me(where: Empty): Doc!
  # getDoc gets a doc at the given ref
  getDoc(where: RefInput!): Doc!
  # searchDocs searches for 0-many docs
  searchDocs(where: Filter!): Docs!
  # traverse searches for 0-many docs using a graph traversal algorithm
  traverse(where: TraverseFilter!): Traversals!
  # traverseMe searches for 0-many docs related to the origin user using a graph traversal algorithm
  traverseMe(where: TraverseMeFilter!): Traversals!
  # getConnection gets a connection at the given ref
  getConnection(where: RefInput!): Connection!
  # existsDoc checks if a document exists in the graph
  existsDoc(where: ExistsFilter!): Boolean!
  # existsConnection checks if a connection exists in the graph
  existsConnection(where: ExistsFilter!): Boolean!
  # hasDoc checks if a document exists in the graph by reference
  hasDoc(where: RefInput!): Boolean!
  # hasConnection checks if a connection exists in the graph by reference
  hasConnection(where: RefInput!): Boolean!
  # searchConnections searches for 0-many connections
  searchConnections(where: Filter!): Connections!
  # connectionsFrom returns connections from the given doc that pass the filter
  connectionsFrom(where: ConnectFilter!): Connections!
  # connectionsTo returns connections to the given doc that pass the filter
  connectionsTo(where: ConnectFilter!): Connections!
  # aggregateDocs executes an aggregation function against a set of documents
  aggregateDocs(where: AggFilter!): Float!
  # aggregateConnections executes an aggregation function against a set of connections
  aggregateConnections(where: AggFilter!): Float!
}

type Subscription {
  # stream opens a stream of messages that pass a filter on a pubsub channel. state changes are sent to the 'state' channel.
  stream(where: StreamFilter!): Message!
}