Pagination - Query language

diggy · August 28, 2020, 4:41pm

Pagination allows returning only a portion, rather than the whole, result set. This can be useful for top-k style queries as well as to reduce the size of the result set for client side processing or to allow paged access to results.

Pagination is often used with sorting.

Note Without a sort order specified, the results are sorted by uid, which is assigned randomly. So the ordering, while deterministic, might not be what you expected.

First

Syntax Examples:

q(func: ..., first: N)
predicate (first: N) { ... }
predicate @filter(...) (first: N) { ... }

For positive N, first: N retrieves the first N results, by sorted or UID order.

For negative N, first: N retrieves the last N results, by sorted or UID order. Currently, negative is only supported when no order is applied. To achieve the effect of a negative with a sort, reverse the order of the sort and use a positive N.

Query Example: Last two films, by UID order, directed by Steven Spielberg and the first three genres of those movies, sorted alphabetically by English name.

{
  me(func: allofterms([email protected], "Steven Spielberg")) {
    director.film (first: -2) {
      [email protected]
      initial_release_date
      genre (orderasc: [email protected]) (first: 3) {
          [email protected]
      }
    }
  }
}

{ me(func: allofterms(name@en, "Steven Spielberg")) { director.film (first: -2) { name@en initial_release_date genre (orderasc: name@en) (first: 3) { name@en } } } }

curl -H "Content-Type: application/graphql+-" localhost:8080/query -XPOST -d '  blahblah' | python -m json.tool | less

package main
import (
	"context"
	"flag"
	"fmt"
	"log"
    
	"github.com/dgraph-io/dgo/v2"
	"github.com/dgraph-io/dgo/v2/protos/api"
    
	"google.golang.org/grpc"
)
var (
	dgraph = flag.String("d", "127.0.0.1:9080", "Dgraph Alpha address")
)
func main() {
	flag.Parse()
	conn, err := grpc.Dial(*dgraph, grpc.WithInsecure())
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	dg := dgo.NewDgraphClient(api.NewDgraphClient(conn))
    
	resp, err := dg.NewTxn().Query(context.Background(), `blahblah`)
	
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Response: %s\n", resp.Json)
}

import io.dgraph.DgraphClient;
import io.dgraph.DgraphGrpc;
import io.dgraph.DgraphGrpc.DgraphStub;
import io.dgraph.DgraphProto.Response;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;
import java.util.Map;
public class App {
    public static void main(final String[] args) {
        ManagedChannel channel =
            ManagedChannelBuilder.forAddress("localhost", 9080).usePlaintext(true).build();
        DgraphStub stub = DgraphGrpc.newStub(channel);
        DgraphClient dgraphClient = new DgraphClient(stub);
        String query = "blahblah";
    
        Response res = dgraphClient.newTransaction().query(query);
    
        System.out.printf("Response: %s", res.getJson().toStringUtf8());
    }
}

import pydgraph
import json
def main():
    client_stub = pydgraph.DgraphClientStub("localhost:9080")
    client = pydgraph.DgraphClient(client_stub)
    query = """blahblah"""
    res = client.txn(read_only=True).query(query)
    print('Response: {}'.format(json.loads(res.json)))
    client_stub.close()
if __name__ == '__main__':
    try:
        main()
    except Exception as e:
        print('Error: {}'.format(e))

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 = `blahblah`;
  const response = await dgraphClient.newTxn().query(query);
  console.log("Response: ", JSON.stringify(response.getJson()));
  clientStub.close();
}
main().then().catch((e) => {
  console.log("ERROR: ", e);
});

const dgraph = require("dgraph-js-http");
async function main() {
  const clientStub = new dgraph.DgraphClientStub("http://localhost:8080");
  const dgraphClient = new dgraph.DgraphClient(clientStub);
  const query = `blahblah`;
  const response = await dgraphClient.newTxn().query(query);
  console.log("Response: ", JSON.stringify(response.data));
}
main().then().catch((e) => {
  console.log("ERROR: ", e);
});

Query Example: The three directors named Steven who have directed the most actors of all directors named Steven.

{
  ID as var(func: allofterms([email protected], "Steven")) @filter(has(director.film)) {
    director.film {
      stars as count(starring)
    }
    totalActors as sum(val(stars))
  }
  mostStars(func: uid(ID), orderdesc: val(totalActors), first: 3) {
    [email protected]
    stars : val(totalActors)
    director.film {
      [email protected]
    }
  }
}

{ ID as var(func: allofterms(name@en, "Steven")) @filter(has(director.film)) { director.film { stars as count(starring) } totalActors as sum(val(stars)) } mostStars(func: uid(ID), orderdesc: val(totalActors), first: 3) { name@en stars : val(totalActors) director.film { name@en } } }

curl -H "Content-Type: application/graphql+-" localhost:8080/query -XPOST -d '  blahblah' | python -m json.tool | less

package main
import (
	"context"
	"flag"
	"fmt"
	"log"
    
	"github.com/dgraph-io/dgo/v2"
	"github.com/dgraph-io/dgo/v2/protos/api"
    
	"google.golang.org/grpc"
)
var (
	dgraph = flag.String("d", "127.0.0.1:9080", "Dgraph Alpha address")
)
func main() {
	flag.Parse()
	conn, err := grpc.Dial(*dgraph, grpc.WithInsecure())
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	dg := dgo.NewDgraphClient(api.NewDgraphClient(conn))
    
	resp, err := dg.NewTxn().Query(context.Background(), `blahblah`)
	
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Response: %s\n", resp.Json)
}

import io.dgraph.DgraphClient;
import io.dgraph.DgraphGrpc;
import io.dgraph.DgraphGrpc.DgraphStub;
import io.dgraph.DgraphProto.Response;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;
import java.util.Map;
public class App {
    public static void main(final String[] args) {
        ManagedChannel channel =
            ManagedChannelBuilder.forAddress("localhost", 9080).usePlaintext(true).build();
        DgraphStub stub = DgraphGrpc.newStub(channel);
        DgraphClient dgraphClient = new DgraphClient(stub);
        String query = "blahblah";
    
        Response res = dgraphClient.newTransaction().query(query);
    
        System.out.printf("Response: %s", res.getJson().toStringUtf8());
    }
}

import pydgraph
import json
def main():
    client_stub = pydgraph.DgraphClientStub("localhost:9080")
    client = pydgraph.DgraphClient(client_stub)
    query = """blahblah"""
    res = client.txn(read_only=True).query(query)
    print('Response: {}'.format(json.loads(res.json)))
    client_stub.close()
if __name__ == '__main__':
    try:
        main()
    except Exception as e:
        print('Error: {}'.format(e))

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 = `blahblah`;
  const response = await dgraphClient.newTxn().query(query);
  console.log("Response: ", JSON.stringify(response.getJson()));
  clientStub.close();
}
main().then().catch((e) => {
  console.log("ERROR: ", e);
});

const dgraph = require("dgraph-js-http");
async function main() {
  const clientStub = new dgraph.DgraphClientStub("http://localhost:8080");
  const dgraphClient = new dgraph.DgraphClient(clientStub);
  const query = `blahblah`;
  const response = await dgraphClient.newTxn().query(query);
  console.log("Response: ", JSON.stringify(response.data));
}
main().then().catch((e) => {
  console.log("ERROR: ", e);
});

Offset

Syntax Examples:

q(func: ..., offset: N)
predicate (offset: N) { ... }
predicate (first: M, offset: N) { ... }
predicate @filter(...) (offset: N) { ... }

With offset: N the first N results are not returned. Used in combination with first, first: M, offset: N skips over N results and returns the following M.

Query Example: Order Hark Tsui’s films by English title, skip over the first 4 and return the following 6.

{
  me(func: allofterms([email protected], "Hark Tsui")) {
    [email protected]
    [email protected]
    director.film (orderasc: [email protected]) (first:6, offset:4)  {
      genre {
        [email protected]
      }
      [email protected]
      [email protected]
      initial_release_date
    }
  }
}

{ me(func: allofterms(name@en, "Hark Tsui")) { name@zh name@en director.film (orderasc: name@en) (first:6, offset:4) { genre { name@en } name@zh name@en initial_release_date } } }

curl -H "Content-Type: application/graphql+-" localhost:8080/query -XPOST -d '  blahblah' | python -m json.tool | less

package main
import (
	"context"
	"flag"
	"fmt"
	"log"
    
	"github.com/dgraph-io/dgo/v2"
	"github.com/dgraph-io/dgo/v2/protos/api"
    
	"google.golang.org/grpc"
)
var (
	dgraph = flag.String("d", "127.0.0.1:9080", "Dgraph Alpha address")
)
func main() {
	flag.Parse()
	conn, err := grpc.Dial(*dgraph, grpc.WithInsecure())
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	dg := dgo.NewDgraphClient(api.NewDgraphClient(conn))
    
	resp, err := dg.NewTxn().Query(context.Background(), `blahblah`)
	
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Response: %s\n", resp.Json)
}

import io.dgraph.DgraphClient;
import io.dgraph.DgraphGrpc;
import io.dgraph.DgraphGrpc.DgraphStub;
import io.dgraph.DgraphProto.Response;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;
import java.util.Map;
public class App {
    public static void main(final String[] args) {
        ManagedChannel channel =
            ManagedChannelBuilder.forAddress("localhost", 9080).usePlaintext(true).build();
        DgraphStub stub = DgraphGrpc.newStub(channel);
        DgraphClient dgraphClient = new DgraphClient(stub);
        String query = "blahblah";
    
        Response res = dgraphClient.newTransaction().query(query);
    
        System.out.printf("Response: %s", res.getJson().toStringUtf8());
    }
}

import pydgraph
import json
def main():
    client_stub = pydgraph.DgraphClientStub("localhost:9080")
    client = pydgraph.DgraphClient(client_stub)
    query = """blahblah"""
    res = client.txn(read_only=True).query(query)
    print('Response: {}'.format(json.loads(res.json)))
    client_stub.close()
if __name__ == '__main__':
    try:
        main()
    except Exception as e:
        print('Error: {}'.format(e))

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 = `blahblah`;
  const response = await dgraphClient.newTxn().query(query);
  console.log("Response: ", JSON.stringify(response.getJson()));
  clientStub.close();
}
main().then().catch((e) => {
  console.log("ERROR: ", e);
});

const dgraph = require("dgraph-js-http");
async function main() {
  const clientStub = new dgraph.DgraphClientStub("http://localhost:8080");
  const dgraphClient = new dgraph.DgraphClient(clientStub);
  const query = `blahblah`;
  const response = await dgraphClient.newTxn().query(query);
  console.log("Response: ", JSON.stringify(response.data));
}
main().then().catch((e) => {
  console.log("ERROR: ", e);
});

After

Syntax Examples:

q(func: ..., after: UID)
predicate (first: N, after: UID) { ... }
predicate @filter(...) (first: N, after: UID) { ... }

Another way to get results after skipping over some results is to use the default UID ordering and skip directly past a node specified by UID. For example, a first query could be of the form predicate (after: 0x0, first: N), or just predicate (first: N), with subsequent queries of the form predicate(after: <uid of last entity in last result>, first: N).

Query Example: The first five of Baz Luhrmann’s films, sorted by UID order.

{
  me(func: allofterms([email protected], "Baz Luhrmann")) {
    [email protected]
    director.film (first:5) {
      uid
      [email protected]
    }
  }
}

{ me(func: allofterms(name@en, "Baz Luhrmann")) { name@en director.film (first:5) { uid name@en } } }

curl -H "Content-Type: application/graphql+-" localhost:8080/query -XPOST -d '  blahblah' | python -m json.tool | less

package main
import (
	"context"
	"flag"
	"fmt"
	"log"
    
	"github.com/dgraph-io/dgo/v2"
	"github.com/dgraph-io/dgo/v2/protos/api"
    
	"google.golang.org/grpc"
)
var (
	dgraph = flag.String("d", "127.0.0.1:9080", "Dgraph Alpha address")
)
func main() {
	flag.Parse()
	conn, err := grpc.Dial(*dgraph, grpc.WithInsecure())
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	dg := dgo.NewDgraphClient(api.NewDgraphClient(conn))
    
	resp, err := dg.NewTxn().Query(context.Background(), `blahblah`)
	
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Response: %s\n", resp.Json)
}

import io.dgraph.DgraphClient;
import io.dgraph.DgraphGrpc;
import io.dgraph.DgraphGrpc.DgraphStub;
import io.dgraph.DgraphProto.Response;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;
import java.util.Map;
public class App {
    public static void main(final String[] args) {
        ManagedChannel channel =
            ManagedChannelBuilder.forAddress("localhost", 9080).usePlaintext(true).build();
        DgraphStub stub = DgraphGrpc.newStub(channel);
        DgraphClient dgraphClient = new DgraphClient(stub);
        String query = "blahblah";
    
        Response res = dgraphClient.newTransaction().query(query);
    
        System.out.printf("Response: %s", res.getJson().toStringUtf8());
    }
}

import pydgraph
import json
def main():
    client_stub = pydgraph.DgraphClientStub("localhost:9080")
    client = pydgraph.DgraphClient(client_stub)
    query = """blahblah"""
    res = client.txn(read_only=True).query(query)
    print('Response: {}'.format(json.loads(res.json)))
    client_stub.close()
if __name__ == '__main__':
    try:
        main()
    except Exception as e:
        print('Error: {}'.format(e))

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 = `blahblah`;
  const response = await dgraphClient.newTxn().query(query);
  console.log("Response: ", JSON.stringify(response.getJson()));
  clientStub.close();
}
main().then().catch((e) => {
  console.log("ERROR: ", e);
});

const dgraph = require("dgraph-js-http");
async function main() {
  const clientStub = new dgraph.DgraphClientStub("http://localhost:8080");
  const dgraphClient = new dgraph.DgraphClient(clientStub);
  const query = `blahblah`;
  const response = await dgraphClient.newTxn().query(query);
  console.log("Response: ", JSON.stringify(response.data));
}
main().then().catch((e) => {
  console.log("ERROR: ", e);
});

The fifth movie is the Australian movie classic Strictly Ballroom. It has UID 0x99e44. The results after Strictly Ballroom can now be obtained with after.

{
  me(func: allofterms([email protected], "Baz Luhrmann")) {
    [email protected]
    director.film (first:5, after: 0x99e44) {
      uid
      [email protected]
    }
  }
}

{ me(func: allofterms(name@en, "Baz Luhrmann")) { name@en director.film (first:5, after: 0x99e44) { uid name@en } } }

curl -H "Content-Type: application/graphql+-" localhost:8080/query -XPOST -d '  blahblah' | python -m json.tool | less

package main
import (
	"context"
	"flag"
	"fmt"
	"log"
    
	"github.com/dgraph-io/dgo/v2"
	"github.com/dgraph-io/dgo/v2/protos/api"
    
	"google.golang.org/grpc"
)
var (
	dgraph = flag.String("d", "127.0.0.1:9080", "Dgraph Alpha address")
)
func main() {
	flag.Parse()
	conn, err := grpc.Dial(*dgraph, grpc.WithInsecure())
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	dg := dgo.NewDgraphClient(api.NewDgraphClient(conn))
    
	resp, err := dg.NewTxn().Query(context.Background(), `blahblah`)
	
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Response: %s\n", resp.Json)
}

import io.dgraph.DgraphClient;
import io.dgraph.DgraphGrpc;
import io.dgraph.DgraphGrpc.DgraphStub;
import io.dgraph.DgraphProto.Response;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;
import java.util.Map;
public class App {
    public static void main(final String[] args) {
        ManagedChannel channel =
            ManagedChannelBuilder.forAddress("localhost", 9080).usePlaintext(true).build();
        DgraphStub stub = DgraphGrpc.newStub(channel);
        DgraphClient dgraphClient = new DgraphClient(stub);
        String query = "blahblah";
    
        Response res = dgraphClient.newTransaction().query(query);
    
        System.out.printf("Response: %s", res.getJson().toStringUtf8());
    }
}

import pydgraph
import json
def main():
    client_stub = pydgraph.DgraphClientStub("localhost:9080")
    client = pydgraph.DgraphClient(client_stub)
    query = """blahblah"""
    res = client.txn(read_only=True).query(query)
    print('Response: {}'.format(json.loads(res.json)))
    client_stub.close()
if __name__ == '__main__':
    try:
        main()
    except Exception as e:
        print('Error: {}'.format(e))

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 = `blahblah`;
  const response = await dgraphClient.newTxn().query(query);
  console.log("Response: ", JSON.stringify(response.getJson()));
  clientStub.close();
}
main().then().catch((e) => {
  console.log("ERROR: ", e);
});

const dgraph = require("dgraph-js-http");
async function main() {
  const clientStub = new dgraph.DgraphClientStub("http://localhost:8080");
  const dgraphClient = new dgraph.DgraphClient(clientStub);
  const query = `blahblah`;
  const response = await dgraphClient.newTxn().query(query);
  console.log("Response: ", JSON.stringify(response.data));
}
main().then().catch((e) => {
  console.log("ERROR: ", e);
});

This is a companion discussion topic for the original entry at https://dgraph.io/docs/query-language/pagination/

Topic		Replies	Views
Keyset pagination with ordering using a deterministic approach Users kind:question , dql	6	592	May 31, 2022
Pagination using "after" seems to ignore sorting Users	3	694	May 4, 2020
Order results by a pre-sorted list GraphQL ordering	0	519	May 28, 2021
UID variables, cascade, and pagination with first Issues status:accepted , kind:bug , ticket:created	2	1025	January 11, 2022
Expected behaviour for sort queries Dgraph discussion	16	2144	March 25, 2021

Pagination - Query language

First

Offset

After

Related Topics