Dgraph APIs

Execute queries and mutations against a Dgraph database

While each Modus SDK offers similar capabilities, the APIs and usage may vary between languages.

Modus Dgraph APIs documentation is available on the following pages:

• AssemblyScript Dgraph APIs(this page)
• Go Dgraph APIs

The Modus Dgraph APIs allow you to run queries and mutations against a Dgraph database.

Import

To begin, import the dgraph namespace from the SDK:

import { dgraph } from "@hypermode/modus-sdk-as"

Dgraph APIs

The APIs in the dgraph namespace are below, organized by category.

We’re constantly introducing new APIs through ongoing development with early users. Please open an issue if you have ideas on what would make Modus even more powerful for your next app!

Functions

alterSchema

Alter the schema of a Dgraph database.

function alterSchema(connection: string, schema: string): string

connection · string · required

Name of the connection, as defined in the manifest.

schema · string · required

The schema to apply to the Dgraph database.

dropAll

Drop all data from a Dgraph database.

function dropAll(connection: string): string

connection · string · required

Name of the connection, as defined in the manifest.

dropAttr

Drop an attribute from a Dgraph schema.

function dropAttr(connection: string, attr: string): string

connection · string · required

Name of the connection, as defined in the manifest.

attr · string · required

The attribute to drop from the Dgraph schema.

escapeRDF

Ensures proper escaping of RDF string literals.

function escapeRDF(value: string): string

value · string · required

The RDF string literal to escape.

executeMutations

Execute one or more mutations, without a filtering query.

If you need to filter the mutations based on a query, use the executeQuery function instead, and pass the mutations after the query.

function executeMutations(
  connection: string,
  ...mutations: Mutation[]
): Response

connection · string · required

Name of the connection, as defined in the manifest.

mutations · ...Mutation[] · required

One or more Mutation objects to execute.

executeQuery

Execute a DQL query to retrieve data from a Dgraph database.

Also used to execute a filtering query and apply one or more mutations to the result of the query.

If you need apply mutations without a filtering query, use the executeMutations function instead.

function executeQuery(
  connection: string,
  query: Query,
  ...mutations: Mutation[]
): Response

connection · string · required

Name of the connection, as defined in the manifest.

request · Query · required

A Query object describing the DQL query to execute.

mutations · ...Mutation[]

Optional parameters specifying one or more Mutation objects to execute on the nodes matched by the query.

Types

Mutation

A Dgraph mutation object, used to execute mutations.

class Mutation {
  setJson: string
  delJson: string
  setNquads: string
  delNquads: string
  condition: string
  withSetJson(json: string): Mutation
  withDelJson(json: string): Mutation
  withSetNquads(nquads: string): Mutation
  withDelNquads(nquads: string): Mutation
  withCondition(cond: string): Mutation
}

new dgraph.Mutation(setJson, delJson, setNquads, delNquads, condition)

Creates a new Mutation object with the given setJson, delJson, setNquads, delNquads, and condition fields.

setJson · string

A JSON string representing the data to set in the mutation.

delJson · string

A JSON string representing the data to delete in the mutation.

setNquads · string

A string representing the data to set in the mutation in RDF N-Quads format.

delNquads · string

A string representing the data to delete in the mutation in RDF N-Quads format.

condition · string

A string representing the condition query for the mutation, as a DQL @if directive.

withSetJson(json)

Sets the setJson field of the mutation to the given json string. Returns the Mutation object to allow for method chaining.

withDelJson(json)

Sets the delJson field of the mutation to the given json string. Returns the Mutation object to allow for method chaining.

withSetNquads(nquads)

Sets the setNquads field of the mutation to the given nquads string. Returns the Mutation object to allow for method chaining.

withDelNquads(nquads)

Sets the delNquads field of the mutation to the given nquads string. Returns the Mutation object to allow for method chaining.

withCondition(cond)

Sets the condition field of the mutation to the given cond string, which should be a DQL @if directive. Returns the Mutation object to allow for method chaining.

Query

A Dgraph query object, used to execute queries.

class Query {
  query: string = ""
  variables: Map<string, string> = new Map<string, string>()
  withVariable<T>(name: string, value: T): this
}

new dgraph.Query(query, variables)

Creates a new Query object with the given query and variables. query is a Dgraph Query Language (DQL) query string, and variables is an optional Variables object.

query · string

The DQL query to execute.

variables · Map<string, string>

A map of query variables, with values encoded as JSON strings.

withVariable(name, value)

Sets a query variable with the given name and value. name is of type string, and value can be a string, number, or boolean.

Returns the Query object to allow for method chaining.

The withVariable method is the preferred way to set query variables in a Query object, and allows for fluent method chaining to add multiple variables. For example:

const query = new Query(`
  query all($name: string, $age: int) {
    all(func: eq(name, $name)) {
      name
      age
    }
  }
`)
  .withVariable("name", "Alice")
  .withVariable("age", 30)

const response = dgraph.executeQuery("my-dgraph-connection", query)

Request

A Dgraph request object, used to execute queries and mutations.

This object was used by the execute function, which has been replaced by the executeQuery and executeMutations functions. You should no longer need to create a Request object directly.

class Request {
  query: Query = new Query()
  mutations: Mutation[] = []
}

new dgraph.Request(query, mutations)

Creates a new Request object with the given query and mutations.

The query and mutations fields are optional and default to null.

query · Query

A Dgraph query object.

mutations · Mutation[]

An array of Dgraph mutation objects.

Variables

A Variables object used to set query variables in a Dgraph query.

As of SDK version 0.17.1, it’s no longer necessary to explicitly create a Variables object. Instead, use the withVariable method on the Query object to set query variables.

class Variables {
  set<T>(name: string, value: T): void
  toMap(): Map<string, string>
}

Variables.set(name, value)

Sets a query variable with the given name and value. name is of type string, and value can be a string, number, or boolean.

Variables.toMap()

Returns a map of all query variables set in the Variables object, with values encoded as strings.