Name	Name	Last commit message	Last commit date
parent directory ..
src	src
test	test
CHANGELOG.md	CHANGELOG.md
README.md	README.md
jest.config.js	jest.config.js
package.json	package.json
tsconfig.build.json	tsconfig.build.json
tsconfig.json	tsconfig.json

Dgraphium Core (QueryBuilder)

Query builder for Dgraph database.

Install
Projection
- Projection Merging
Operators
Connecting Operators
Filtering
Pagination
Directives
Query Variables (refs)
GraphQL Types
Running a Query
Demo

Install

Install using npm:

npm install @dgraphium/core

or yarn:

yarn add @dgraphium/core

Projection

Projection is basically an edge definition. Separately it can be defined by: edge({...}) which is exported from @dgraphium/core.

To define projection for a query:

  query(...).project({ /* projection here */ })

For describing an edge, object is used. Object almost looks like the returned value.

Each key's value type in the projection object can be:

1 | true: include field in a result.
- if you pass type to containing edge/projection, key maps to field: ${capitalized type}.${key}
- if type is undefined, key maps to field with same name: ${key}
0 | false: don't include field in a result.
string: key will map to passed value. Key simply maps to it so the output will be: ${key}: ${value}
Edge: nested edge.
Ref: query/value reference.

Projection Merging

You can call query.project(...) multiple times on same query object.

By default projections will deeply merge. New keys will be added, existing keys will be overwritten.

For example:

query.project({ a: 1, c: { d: 1 } });
query.project({ b: 1, c: { d: 0, k: 1 } });
/* resulting projection: {
  a: 1,
  b: 1 ,
  c: { d: 0, k: 1 }
} */

You can do projection merging on Edge as well using: edge.merge({...}).

To overwrite projection, you can set overwrite to true:

query.project({ a: 1 });
query.project({ b: 1 }, true);
// resulting projection: { b: 1 }

In case of Edge: edge.merge({...}, true)

Operators

Operators/Functions can be imported from @dgraphium/core/operators.

Supported operators:

basic operators

operator	description
`type`	search by Type
`has`	find nodes which has field/edge/predicate
`uid`	find by uid
`predUid`	find by nested edge's uid

simple comparison operators

operator	description
`eq`	equals
`lt`	less than
`lte`	less than or equal to
`gt`	greater than
`gte`	greater than or equal to

text operators

operator	description
`regex`	regex search
`match`	fuzzy matching
`anyOfText`	full-text search with stemming and stop words to find strings matching any of the given text
`allOfText`	full-text search with stemming and stop words to find strings matching all of the given text
`anyOfTerms`	matches strings that have any of the specified terms in any order; case insensitive.
`allOfTerms`	matches strings that have all of the specified terms in any order; case insensitive.

Connecting Operators

Note: connecting operators (LogicalOperators) can't be used in query.func(...).

they can be imported by:

import { and, or, not } from '@dgraphium/core/operators';

Filtering

Operators can be used in filtering queries or nested edges.

filtering queries:

For example fetch users with age between 18 and 30: query().filter(and(gt('age', 18), lt('age', 30)))
filtering nested edges: For example fetch user's posts, which has more than 10 likes:
```
query().projection({
  posts: edge().filter(gt('likes', 10)),
});
```

Pagination

All pagination methods are available for queries as well as nested edges.

.first(first: number): count of nodes to fetch (same as limit).
.offset(offset: number): node offset or amount of nodes to skip.
.after(id: Uid): fetch nodes after the id.

you can also use

.withArgs(args: {
  first: number,
  offset: number,
  after: Uid,
})

Directives

Query and Edge directives:

cascade

Query only directives:

ignoreReflex
recurse

Those directives are available on edge or query as a function, e.g. edge.cascase().

Query Variables (refs)

Query variable (ref) can be created by calling ref(...path: string[]) method on query object. path argument is a path to a field.

Note: unlike DQL, you can define as many refs as you want. Unless you use it somewhere, it will not be defined in the resulting query.

Query refs can be used either in projection (in which case field will point to val(varName)), or in func/filtering.

Path does not exist in query projection

New field will be added to varQuery projection and ref will point to it.

Examples

const varQuery = query().func(gt('age', 10));
const postsQuery = query()
  .func(uid(varQuery.ref('posts')))
  .project({ text: 1 });

postsQuery.toString() outputs:

{
    var(func: gt(age, 10)) {
      posts: v1 as posts
    }

    q1(func: uid(v1)) {
      text: text
    }
}

Path exists in query projection

Ref will point to whatever is at the given path.

Examples

pointed field with filtering:

const varQuery = query()
  .func(gt('age', 10))
  .project({
    posts: edge().filter(regex('text', /mysql/))
  });
const postsQuery = query()
  .func(uid(varQuery.ref('posts')))
  .project({ text: 1 });

postsQuery.toString() outputs:

{
    var(func: gt(age, 10)) {
      posts: v1 as posts @filter(regexp(text, /mysql/)) {
      }
    }

    q1(func: uid(v1)) {
      text: text
    }
}

graphql type field:

const varQuery = query('user')
  .func(gt('age', 10))
  .project({
    posts: edge('post').filter(regex('text', /mysql/)),
  });
const postsQuery = query('post')
  .func(uid(varQuery.ref('posts')))
  .project({ text: 1 });

postsQuery.toString() outputs:

{
    var(func: gt(User.age, 10)) {
      posts: v1 as User.posts @filter(regexp(Post.text, /mysql/)) {
      }
    }

    q1(func: uid(v1)) {
      text: Post.text
    }
}

GraphQL Types

If you have GraphQL schema, when you deploy that schema to Dgraph database, each field gets prefixed by it's type.

for example:

type User {
    id: ID!
    name: String!
    age: Int!
    posts: [Post]
}

type Post {
  id: ID!
  text: String!
  replyCount: Int
}

results in following Dgraph schema:

type User {
  User.name
  User.age
  User.posts
}

type Post {
  Post.text
  Post.replyCount
}

User.name: string
User.age: int
User.posts: [uid]

so to query such data, you need to prefix each field with it's type:

{
  me(func: uid(0x2)) {
    id: uid
    name: User.name
    age: User.age
    posts: User.posts @filter(gt(Post.replyCount, 2)) {
      id: uid
      text: Post.text
      replyCount: Post.replyCount
    }
  }
}

to achieve exactly above written query with Dgraphium:

query('user') // <- type User
  .name('me')
  .func(uid('0x2'))
  .project({
    id: 1,
    name: 1,
    age: 1,
    posts: edge('post', { // <- type Post
        id: 1,
        text: 1,
        replyCount: 1,
      })
      .filter(gt('replyCount', 2)),
  })

Combine Queries

you can combine queries with:

import { combine } from '@dgraphium/core';

const combinedQuery = combine(
  query1,
  query2,
  ...
);

Note:

don't call build method on query before passing to combine function.
query names should be unique.

Running a Query

You can run query or group of queries with @dgraphium/client:

await dgraphClient.newTxn().query(meQuery); // params will be included

Note: you can name parameters by: param.name(paramName). For example: params.string('myStrValue').name('myParamName'). This is useful when you want to reuse query and override parameters:

for example:
await dgraphClient.newTxn().queryWithVars(
  queryWithParam,
  { '$myParamName': 'myStrValueNew' }
);

Demo

import { query, edge } from '@dgraphium/core';
import { uid, regex, gt, gte, lt, and, or } from '@dgraphium/core/operators';
const meQuery = query()
  .name('me')
  .func(uid('0x2', '0x3', '0x4'))
  .filter(and(
    or(
      regex('name', /zura/i),
      regex('name', /benashvili/i),
    ),
    gte('age', 15),
    lt('age', 25)
  ))
  .project({
    id: 1, // uid = id
    name: 1,
    age: 1,
    posts: edge({
        id: 1,
        text: 1,
      })
      .filter(gt('createdDate', new Date('2020-01-01')))
      .first(10),
  })
  .first(1)
  .build();

meQuery.toString() outputs (built query string):

{
  me(func: uid(0x2, 0x3, 0x4), first: 1) @filter((regexp(name, /zura/i) OR regexp(name, /benashvili/i)) AND ge(age, 15) AND lt(age, 25)) {
    id: uid
    name: name
    age: age
    posts: posts (first: 10) @filter(gt(createdDate, 2020-01-01T00:00:00.000Z)) {
      id: uid
      text: text
    }
  }
}

run query with @dgraphium/client:

await dgraphClient.newTxn().query(meQuery);

use GraphQL Variables(params) in query

import { query, edge, params } from '@dgraphium/core';
import { uid, regex, gt, gte, lt, and, or } from '@dgraphium/core/operators';

const meQuery = query()
  .name('me')
  .func(uid(params.uids('0x2', '0x3', '0x4')))
  .filter(and(
    or(
      regex('name', params.regex(/zura/i)),
      regex('name', params.regex(/benashvili/i)),
    ),
    gte('age', params.int(15)),
    lt('age', params.int(25))
  ))
  .project({
    id: 1, // uid = id
    name: 1,
    age: 1,
    posts: edge({
        id: 1,
        text: 1,
      })
      .filter(gt(
        'createdDate',
        params.date(new Date('2020-01-01'))
      ))
      .first(10),
  })
  .first(1)
  .build();

meQuery.toString() outputs (built query string):

query q($p2: string, $p1: string, $p3: string, $p4: string, $p5: int, $p6: int) {
  me(func: uid($p1), first: 1) @filter((regexp(name, $p3) OR regexp(name, $p4)) AND ge(age, $p5) AND lt(age, $p6)) {
    id: uid
    name: name
    age: age
    posts: posts (first: 10) @filter(gt(createdDate, $p2)) {
      id: uid
      text: text
    }
  }
}

run query with @dgraphium/client:

await dgraphClient.newTxn().query(meQuery); // params will be included

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

core

core

README.md

Dgraphium Core (QueryBuilder)

Table of contents

Install

Projection

Projection Merging

Operators

basic operators

simple comparison operators

text operators

Connecting Operators

Filtering

Pagination

Directives

Query Variables (refs)

Path does not exist in query projection

Examples

Path exists in query projection

Examples

GraphQL Types

Combine Queries

Running a Query

Demo

use GraphQL Variables(params) in query

Files

core

Directory actions

More options

Directory actions

More options

Latest commit

History

core

Folders and files

parent directory

README.md

Dgraphium Core (QueryBuilder)

Table of contents

Install

Projection

Projection Merging

Operators

basic operators

simple comparison operators

text operators

Connecting Operators

Filtering

Pagination

Directives

Query Variables (refs)

Path does not exist in query projection

Examples

Path exists in query projection

Examples

GraphQL Types

Combine Queries

Running a Query

Demo

use GraphQL Variables(params) in query