Query parameters

Syntax Examples (using default values):

• query title($name: string = "Bauman") { ... }
• query title($age: int = "95") { ... }
• query title($uids: string = "0x1") { ... }
• query title($uids: string = "[0x1, 0x2, 0x3]") { ... }. The value of the variable is a quoted array.

Variables can be defined and used in queries which helps in query reuse and avoids costly string building in clients at runtime by passing a separate variable map. A variable starts with a $ symbol. For HTTP requests with Query parameters, we must use Content-Type: application/json header and pass data with a JSON object containing query and variables.

curl -H "Content-Type: application/json" localhost:8080/query -XPOST -d $'{
  "query": "query test($a: string) { test(func: eq(name, $a)) { \n uid \n name \n } }",
  "variables": { "$a": "Alice" }
}' | python -m json.tool | less

Query

query test($a: int, $b: int, $name: string) {
  me(func: allofterms(name@en, $name)) {
    name@en
    director.film (first: $a, offset: $b) {
      name @en
      genre(first: $a) {
        name@en
      }
    }
  }
}

Go

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "google.golang.org/grpc"
    "github.com/dgraph-io/dgo/v230"
    "github.com/dgraph-io/dgo/v230/protos/api"
)

func main() {
    conn, err := grpc.Dial("localhost:9080", grpc.WithInsecure())
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    dgraphClient := dgo.NewDgraphClient(api.NewDgraphClient(conn))
    ctx := context.Background()

    txn := dgraphClient.NewTxn()
    defer txn.Discard(ctx)

    query := `query test(\$a: int, \$b: int, \$name: string) {
  me(func: allofterms(name@en, \$name)) {
    name@en
    director.film (first: \$a, offset: \$b) {
      name @en
      genre(first: \$a) {
        name@en
      }
    }
  }
}`
    
    resp, err := txn.Query(ctx, query)
    if err != nil {
        log.Fatal(err)
    }

    var result map[string]interface{}
    json.Unmarshal(resp.Json, &result)
    fmt.Printf("%+v\n", result)
}

Java

import io.dgraph.DgraphClient;
import io.dgraph.DgraphGrpc;
import io.dgraph.DgraphProto;
import io.dgraph.Transaction;

import java.util.Map;

public class App {
    public static void main(String[] args) {
        ManagedChannel channel = ManagedChannelBuilder
            .forAddress("localhost", 9080)
            .usePlaintext()
            .build();
        
        DgraphGrpc.DgraphStub stub = DgraphGrpc.newStub(channel);
        DgraphClient dgraphClient = new DgraphClient(stub);
        
        String query = "query test(\$a: int, \$b: int, \$name: string) {
  me(func: allofterms(name@en, \$name)) {
    name@en
    director.film (first: \$a, offset: \$b) {
      name @en
      genre(first: \$a) {
        name@en
      }
    }
  }
}";
        
        Transaction txn = dgraphClient.newTransaction();
        try {
            DgraphProto.Response response = txn.query(query);
            System.out.println(response.getJson().toStringUtf8());
        } finally {
            txn.discard();
        }
    }
}

Python

import grpc
from dgraph import DgraphClient, Txn

def main():
    client_stub = DgraphClient("localhost:9080")
    client = DgraphClient(client_stub)
    
    query = """query test(\$a: int, \$b: int, \$name: string) {
  me(func: allofterms(name@en, \$name)) {
    name@en
    director.film (first: \$a, offset: \$b) {
      name @en
      genre(first: \$a) {
        name@en
      }
    }
  }
}"""
    
    txn = client.txn()
    try:
        response = txn.query(query)
        print(response.json)
    finally:
        txn.discard()

if __name__ == "__main__":
    main()

JavaScript (gRPC)

const dgraph = require("dgraph-js");
const grpc = require("grpc");

async function main() {
    const clientStub = new dgraph.DgraphClientStub(
        "localhost:9080",
        grpc.credentials.createInsecure()
    );
    const dgraphClient = new dgraph.DgraphClient(clientStub);
    
    const query = `query test(\$a: int, \$b: int, \$name: string) {
  me(func: allofterms(name@en, \$name)) {
    name@en
    director.film (first: \$a, offset: \$b) {
      name @en
      genre(first: \$a) {
        name@en
      }
    }
  }
}`;
    
    const txn = dgraphClient.newTxn();
    try {
        const res = await txn.query(query);
        const json = res.getJson();
        console.log(JSON.stringify(JSON.parse(json), null, 2));
    } finally {
        await txn.discard();
    }
}

main().catch((e) => {
    console.error(e);
});

JavaScript (HTTP)

const fetch = require("node-fetch");

async function main() {
    const query = `query test(\$a: int, \$b: int, \$name: string) {
  me(func: allofterms(name@en, \$name)) {
    name@en
    director.film (first: \$a, offset: \$b) {
      name @en
      genre(first: \$a) {
        name@en
      }
    }
  }
}`;
    
    const response = await fetch("http://localhost:8080/query", {
        method: "POST",
        headers: {
            "Content-Type": "application/dql"
        },
        body: query
    });
    
    const result = await response.json();
    console.log(JSON.stringify(result, null, 2));
}

main().catch((e) => {
    console.error(e);
});

Curl

curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/dql" \
  -d 'query test($a: int, $b: int, $name: string) {
  me(func: allofterms(name@en, $name)) {
    name@en
    director.film (first: $a, offset: $b) {
      name @en
      genre(first: $a) {
        name@en
      }
    }
  }
}'

• Variables can have default values. In the example below, $a has a default value of 2. Since the value for $a isn't provided in the variable map, $a takes on the default value.
• Variables whose type is suffixed with a ! can't have a default value but must have a value as part of the variables map.
• The value of the variable must be parsable to the given type, if not, an error is thrown.
• The variable types that are supported as of now are: int, float, bool and string.
• Any variable that is being used must be declared in the named query clause in the beginning.

Query

{{< runnable vars="{\"$b\": \"10\", \"$name\": \"Steven Spielberg\"}" >}}
query test($a: int = 2, $b: int!, $name: string) {
  me(func: allofterms(name@en, $name)) {
    director.film (first: $a, offset: $b) {
      genre(first: $a) {
        name@en
      }
    }
  }
}

Go

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "google.golang.org/grpc"
    "github.com/dgraph-io/dgo/v230"
    "github.com/dgraph-io/dgo/v230/protos/api"
)

func main() {
    conn, err := grpc.Dial("localhost:9080", grpc.WithInsecure())
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    dgraphClient := dgo.NewDgraphClient(api.NewDgraphClient(conn))
    ctx := context.Background()

    txn := dgraphClient.NewTxn()
    defer txn.Discard(ctx)

    query := `{{< runnable vars="{\"\$b\": \"10\", \"\$name\": \"Steven Spielberg\"}" >}}
query test(\$a: int = 2, \$b: int!, \$name: string) {
  me(func: allofterms(name@en, \$name)) {
    director.film (first: \$a, offset: \$b) {
      genre(first: \$a) {
        name@en
      }
    }
  }
}`
    
    resp, err := txn.Query(ctx, query)
    if err != nil {
        log.Fatal(err)
    }

    var result map[string]interface{}
    json.Unmarshal(resp.Json, &result)
    fmt.Printf("%+v\n", result)
}

Java

import io.dgraph.DgraphClient;
import io.dgraph.DgraphGrpc;
import io.dgraph.DgraphProto;
import io.dgraph.Transaction;

import java.util.Map;

public class App {
    public static void main(String[] args) {
        ManagedChannel channel = ManagedChannelBuilder
            .forAddress("localhost", 9080)
            .usePlaintext()
            .build();
        
        DgraphGrpc.DgraphStub stub = DgraphGrpc.newStub(channel);
        DgraphClient dgraphClient = new DgraphClient(stub);
        
        String query = "{{< runnable vars=\"{\\"\$b\\": \\"10\\", \\"\$name\\": \\"Steven Spielberg\\"}\" >}}
query test(\$a: int = 2, \$b: int!, \$name: string) {
  me(func: allofterms(name@en, \$name)) {
    director.film (first: \$a, offset: \$b) {
      genre(first: \$a) {
        name@en
      }
    }
  }
}";
        
        Transaction txn = dgraphClient.newTransaction();
        try {
            DgraphProto.Response response = txn.query(query);
            System.out.println(response.getJson().toStringUtf8());
        } finally {
            txn.discard();
        }
    }
}

Python

import grpc
from dgraph import DgraphClient, Txn

def main():
    client_stub = DgraphClient("localhost:9080")
    client = DgraphClient(client_stub)
    
    query = """{{< runnable vars="{\"\$b\": \"10\", \"\$name\": \"Steven Spielberg\"}" >}}
query test(\$a: int = 2, \$b: int!, \$name: string) {
  me(func: allofterms(name@en, \$name)) {
    director.film (first: \$a, offset: \$b) {
      genre(first: \$a) {
        name@en
      }
    }
  }
}"""
    
    txn = client.txn()
    try:
        response = txn.query(query)
        print(response.json)
    finally:
        txn.discard()

if __name__ == "__main__":
    main()

JavaScript (gRPC)

const dgraph = require("dgraph-js");
const grpc = require("grpc");

async function main() {
    const clientStub = new dgraph.DgraphClientStub(
        "localhost:9080",
        grpc.credentials.createInsecure()
    );
    const dgraphClient = new dgraph.DgraphClient(clientStub);
    
    const query = `{{< runnable vars="{\"\$b\": \"10\", \"\$name\": \"Steven Spielberg\"}" >}}
query test(\$a: int = 2, \$b: int!, \$name: string) {
  me(func: allofterms(name@en, \$name)) {
    director.film (first: \$a, offset: \$b) {
      genre(first: \$a) {
        name@en
      }
    }
  }
}`;
    
    const txn = dgraphClient.newTxn();
    try {
        const res = await txn.query(query);
        const json = res.getJson();
        console.log(JSON.stringify(JSON.parse(json), null, 2));
    } finally {
        await txn.discard();
    }
}

main().catch((e) => {
    console.error(e);
});

JavaScript (HTTP)

const fetch = require("node-fetch");

async function main() {
    const query = `{{< runnable vars="{\"\$b\": \"10\", \"\$name\": \"Steven Spielberg\"}" >}}
query test(\$a: int = 2, \$b: int!, \$name: string) {
  me(func: allofterms(name@en, \$name)) {
    director.film (first: \$a, offset: \$b) {
      genre(first: \$a) {
        name@en
      }
    }
  }
}`;
    
    const response = await fetch("http://localhost:8080/query", {
        method: "POST",
        headers: {
            "Content-Type": "application/dql"
        },
        body: query
    });
    
    const result = await response.json();
    console.log(JSON.stringify(result, null, 2));
}

main().catch((e) => {
    console.error(e);
});

Curl

curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/dql" \
  -d '{{< runnable vars="{\"$b\": \"10\", \"$name\": \"Steven Spielberg\"}" >}}
query test($a: int = 2, $b: int!, $name: string) {
  me(func: allofterms(name@en, $name)) {
    director.film (first: $a, offset: $b) {
      genre(first: $a) {
        name@en
      }
    }
  }
}'

You can also use array with Query parameters.

Query

{{< runnable vars="{\"$b\": \"10\", \"$aName\": \"Steven Spielberg\", \"$bName\": \"Quentin Tarantino\"}" >}}
query test($a: int = 2, $b: int!, $aName: string, $bName: string) {
  me(func: eq(name@en, [$aName, $bName])) {
    director.film (first: $a, offset: $b) {
      genre(first: $a) {
        name@en
      }
    }
  }
}

Go

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "google.golang.org/grpc"
    "github.com/dgraph-io/dgo/v230"
    "github.com/dgraph-io/dgo/v230/protos/api"
)

func main() {
    conn, err := grpc.Dial("localhost:9080", grpc.WithInsecure())
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    dgraphClient := dgo.NewDgraphClient(api.NewDgraphClient(conn))
    ctx := context.Background()

    txn := dgraphClient.NewTxn()
    defer txn.Discard(ctx)

    query := `{{< runnable vars="{\"\$b\": \"10\", \"\$aName\": \"Steven Spielberg\", \"\$bName\": \"Quentin Tarantino\"}" >}}
query test(\$a: int = 2, \$b: int!, \$aName: string, \$bName: string) {
  me(func: eq(name@en, [\$aName, \$bName])) {
    director.film (first: \$a, offset: \$b) {
      genre(first: \$a) {
        name@en
      }
    }
  }
}`
    
    resp, err := txn.Query(ctx, query)
    if err != nil {
        log.Fatal(err)
    }

    var result map[string]interface{}
    json.Unmarshal(resp.Json, &result)
    fmt.Printf("%+v\n", result)
}

Java

import io.dgraph.DgraphClient;
import io.dgraph.DgraphGrpc;
import io.dgraph.DgraphProto;
import io.dgraph.Transaction;

import java.util.Map;

public class App {
    public static void main(String[] args) {
        ManagedChannel channel = ManagedChannelBuilder
            .forAddress("localhost", 9080)
            .usePlaintext()
            .build();
        
        DgraphGrpc.DgraphStub stub = DgraphGrpc.newStub(channel);
        DgraphClient dgraphClient = new DgraphClient(stub);
        
        String query = "{{< runnable vars=\"{\\"\$b\\": \\"10\\", \\"\$aName\\": \\"Steven Spielberg\\", \\"\$bName\\": \\"Quentin Tarantino\\"}\" >}}
query test(\$a: int = 2, \$b: int!, \$aName: string, \$bName: string) {
  me(func: eq(name@en, [\$aName, \$bName])) {
    director.film (first: \$a, offset: \$b) {
      genre(first: \$a) {
        name@en
      }
    }
  }
}";
        
        Transaction txn = dgraphClient.newTransaction();
        try {
            DgraphProto.Response response = txn.query(query);
            System.out.println(response.getJson().toStringUtf8());
        } finally {
            txn.discard();
        }
    }
}

Python

import grpc
from dgraph import DgraphClient, Txn

def main():
    client_stub = DgraphClient("localhost:9080")
    client = DgraphClient(client_stub)
    
    query = """{{< runnable vars="{\"\$b\": \"10\", \"\$aName\": \"Steven Spielberg\", \"\$bName\": \"Quentin Tarantino\"}" >}}
query test(\$a: int = 2, \$b: int!, \$aName: string, \$bName: string) {
  me(func: eq(name@en, [\$aName, \$bName])) {
    director.film (first: \$a, offset: \$b) {
      genre(first: \$a) {
        name@en
      }
    }
  }
}"""
    
    txn = client.txn()
    try:
        response = txn.query(query)
        print(response.json)
    finally:
        txn.discard()

if __name__ == "__main__":
    main()

JavaScript (gRPC)

const dgraph = require("dgraph-js");
const grpc = require("grpc");

async function main() {
    const clientStub = new dgraph.DgraphClientStub(
        "localhost:9080",
        grpc.credentials.createInsecure()
    );
    const dgraphClient = new dgraph.DgraphClient(clientStub);
    
    const query = `{{< runnable vars="{\"\$b\": \"10\", \"\$aName\": \"Steven Spielberg\", \"\$bName\": \"Quentin Tarantino\"}" >}}
query test(\$a: int = 2, \$b: int!, \$aName: string, \$bName: string) {
  me(func: eq(name@en, [\$aName, \$bName])) {
    director.film (first: \$a, offset: \$b) {
      genre(first: \$a) {
        name@en
      }
    }
  }
}`;
    
    const txn = dgraphClient.newTxn();
    try {
        const res = await txn.query(query);
        const json = res.getJson();
        console.log(JSON.stringify(JSON.parse(json), null, 2));
    } finally {
        await txn.discard();
    }
}

main().catch((e) => {
    console.error(e);
});

JavaScript (HTTP)

const fetch = require("node-fetch");

async function main() {
    const query = `{{< runnable vars="{\"\$b\": \"10\", \"\$aName\": \"Steven Spielberg\", \"\$bName\": \"Quentin Tarantino\"}" >}}
query test(\$a: int = 2, \$b: int!, \$aName: string, \$bName: string) {
  me(func: eq(name@en, [\$aName, \$bName])) {
    director.film (first: \$a, offset: \$b) {
      genre(first: \$a) {
        name@en
      }
    }
  }
}`;
    
    const response = await fetch("http://localhost:8080/query", {
        method: "POST",
        headers: {
            "Content-Type": "application/dql"
        },
        body: query
    });
    
    const result = await response.json();
    console.log(JSON.stringify(result, null, 2));
}

main().catch((e) => {
    console.error(e);
});

Curl

curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/dql" \
  -d '{{< runnable vars="{\"$b\": \"10\", \"$aName\": \"Steven Spielberg\", \"$bName\": \"Quentin Tarantino\"}" >}}
query test($a: int = 2, $b: int!, $aName: string, $bName: string) {
  me(func: eq(name@en, [$aName, $bName])) {
    director.film (first: $a, offset: $b) {
      genre(first: $a) {
        name@en
      }
    }
  }
}'

We also support variable substitution in facets.

Query

{{< runnable vars="{\"$name\": \"Alice\", \"$IsClose\": \"true\"}" >}}
query test($name: string = "Alice", $IsClose: string = "true") {
  data(func: eq(name, $name)) {
    friend @facets(eq(close, $IsClose)) {
      name
    }
      colleague : friend @facets(eq(close, false)) {
      name
    }
  }
}

Go

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "google.golang.org/grpc"
    "github.com/dgraph-io/dgo/v230"
    "github.com/dgraph-io/dgo/v230/protos/api"
)

func main() {
    conn, err := grpc.Dial("localhost:9080", grpc.WithInsecure())
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    dgraphClient := dgo.NewDgraphClient(api.NewDgraphClient(conn))
    ctx := context.Background()

    txn := dgraphClient.NewTxn()
    defer txn.Discard(ctx)

    query := `{{< runnable vars="{\"\$name\": \"Alice\", \"\$IsClose\": \"true\"}" >}}
query test(\$name: string = "Alice", \$IsClose: string = "true") {
  data(func: eq(name, \$name)) {
    friend @facets(eq(close, \$IsClose)) {
      name
    }
      colleague : friend @facets(eq(close, false)) {
      name
    }
  }
}`
    
    resp, err := txn.Query(ctx, query)
    if err != nil {
        log.Fatal(err)
    }

    var result map[string]interface{}
    json.Unmarshal(resp.Json, &result)
    fmt.Printf("%+v\n", result)
}

Java

import io.dgraph.DgraphClient;
import io.dgraph.DgraphGrpc;
import io.dgraph.DgraphProto;
import io.dgraph.Transaction;

import java.util.Map;

public class App {
    public static void main(String[] args) {
        ManagedChannel channel = ManagedChannelBuilder
            .forAddress("localhost", 9080)
            .usePlaintext()
            .build();
        
        DgraphGrpc.DgraphStub stub = DgraphGrpc.newStub(channel);
        DgraphClient dgraphClient = new DgraphClient(stub);
        
        String query = "{{< runnable vars=\"{\\"\$name\\": \\"Alice\\", \\"\$IsClose\\": \\"true\\"}\" >}}
query test(\$name: string = \"Alice\", \$IsClose: string = \"true\") {
  data(func: eq(name, \$name)) {
    friend @facets(eq(close, \$IsClose)) {
      name
    }
      colleague : friend @facets(eq(close, false)) {
      name
    }
  }
}";
        
        Transaction txn = dgraphClient.newTransaction();
        try {
            DgraphProto.Response response = txn.query(query);
            System.out.println(response.getJson().toStringUtf8());
        } finally {
            txn.discard();
        }
    }
}

Python

import grpc
from dgraph import DgraphClient, Txn

def main():
    client_stub = DgraphClient("localhost:9080")
    client = DgraphClient(client_stub)
    
    query = """{{< runnable vars="{\"\$name\": \"Alice\", \"\$IsClose\": \"true\"}" >}}
query test(\$name: string = "Alice", \$IsClose: string = "true") {
  data(func: eq(name, \$name)) {
    friend @facets(eq(close, \$IsClose)) {
      name
    }
      colleague : friend @facets(eq(close, false)) {
      name
    }
  }
}"""
    
    txn = client.txn()
    try:
        response = txn.query(query)
        print(response.json)
    finally:
        txn.discard()

if __name__ == "__main__":
    main()

JavaScript (gRPC)

const dgraph = require("dgraph-js");
const grpc = require("grpc");

async function main() {
    const clientStub = new dgraph.DgraphClientStub(
        "localhost:9080",
        grpc.credentials.createInsecure()
    );
    const dgraphClient = new dgraph.DgraphClient(clientStub);
    
    const query = `{{< runnable vars="{\"\$name\": \"Alice\", \"\$IsClose\": \"true\"}" >}}
query test(\$name: string = "Alice", \$IsClose: string = "true") {
  data(func: eq(name, \$name)) {
    friend @facets(eq(close, \$IsClose)) {
      name
    }
      colleague : friend @facets(eq(close, false)) {
      name
    }
  }
}`;
    
    const txn = dgraphClient.newTxn();
    try {
        const res = await txn.query(query);
        const json = res.getJson();
        console.log(JSON.stringify(JSON.parse(json), null, 2));
    } finally {
        await txn.discard();
    }
}

main().catch((e) => {
    console.error(e);
});

JavaScript (HTTP)

const fetch = require("node-fetch");

async function main() {
    const query = `{{< runnable vars="{\"\$name\": \"Alice\", \"\$IsClose\": \"true\"}" >}}
query test(\$name: string = "Alice", \$IsClose: string = "true") {
  data(func: eq(name, \$name)) {
    friend @facets(eq(close, \$IsClose)) {
      name
    }
      colleague : friend @facets(eq(close, false)) {
      name
    }
  }
}`;
    
    const response = await fetch("http://localhost:8080/query", {
        method: "POST",
        headers: {
            "Content-Type": "application/dql"
        },
        body: query
    });
    
    const result = await response.json();
    console.log(JSON.stringify(result, null, 2));
}

main().catch((e) => {
    console.error(e);
});

Curl

curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/dql" \
  -d '{{< runnable vars="{\"$name\": \"Alice\", \"$IsClose\": \"true\"}" >}}
query test($name: string = "Alice", $IsClose: string = "true") {
  data(func: eq(name, $name)) {
    friend @facets(eq(close, $IsClose)) {
      name
    }
      colleague : friend @facets(eq(close, false)) {
      name
    }
  }
}'

note

If you want to input a list of uids as a GraphQL variable value, you can have the variable as string type and have the value surrounded by square brackets like ["13", "14"].