Skip to main content
Version: 1.0 (Latest)

Query the database

Once you have created some documents, you can query the database for them. Time to claim your stuff back.

Display database setup

To reproduce the example results from this page, your database needs the following setup.

Database schema
type Book {
  title: String!
  genre: String
  plot: String
  rating: Float
  ratings: [Float]
  author: Person
  seller: Company
}

type Person {
  name: String!
  authoredBooks: [Book]
}

type Company {
  name: String!
  sells: [Book]
}
Documents setup
mutation {
  a1:add_Person(input: {
    name: "George Orwell"
  }) { _docID name }
  a2:add_Person(input: {
    name: "William Golding"
  }) { _docID name }
  a3:add_Person(input: {
    name: "David Foster Wallace"
  }) { _docID name }
  a4:add_Person(input: {
    name: "Victor Hugo"
  }) { _docID name }

  c1:add_Company(input: {
    name: "The Independent Hipster Bookshop"
  }) { _docID name }
  c2:add_Company(input: {
    name: "The World-Destroying Large Chain"
  }) { _docID name }

  b11:add_Book(input: {
    title: "1984",
    genre: "Fiction",
    plot: "A masterpiece of rebellion and imprisonment where war is peace, freedom is slavery, and Big Brother is watching.",
    rating: 4.20,
    ratings: [3.8, 4.91, 3.1, 2.8],
    _authorID: "bae-bc532931-4843-50bc-bbdd-3e31549c8cc6",
    _sellerID: "bae-a5300933-fb0a-5b8f-b38e-202565993ff0"
  }) { _docID title }
  b12:add_Book(input: {
    title: "Down and Out in Paris and London",
    genre: "Memoir",
    plot: "The adventures of a penniless British writer among the down-and-outs of two great cities.",
    rating: 4.09,
    _authorID: "bae-bc532931-4843-50bc-bbdd-3e31549c8cc6",
    _sellerID: "bae-a5300933-fb0a-5b8f-b38e-202565993ff0"
  }) { _docID title }
  b21:add_Book(input: {
    title: "Lord of the Flies",
    genre: "Fiction",
    plot: "At the dawn of the next world war, a plane crashes on an uncharted island, stranding a group of schoolboys.",
    rating: 3.70,
    _authorID: "bae-6025af65-e57e-5db5-84dd-d349b130c6d9",
    _sellerID: "bae-a5300933-fb0a-5b8f-b38e-202565993ff0"
  }) { _docID title }
  b31:add_Book(input: {
    title: "Infinite Jest",
    genre: "Fiction",
    plot: "A gargantuan, mind-altering tragi-comedy about the Pursuit of Happiness in America.",
    rating: 4.25,
    ratings: [3.1, 4.1, 4.5],
    _authorID: "bae-26c791a7-fa81-5d86-95c5-4119e2fef915",
    _sellerID: "bae-81d5fadb-c2a3-5d95-b235-a220c220bf79"
  }) { _docID title }
  b32:add_Book(input: {
    title: "Consider the Lobster and Other Essays",
    genre: "Nonfiction",
    plot: "Do lobsters feel pain? Did Franz Kafka have a funny bone? What is John Updike's deal, anyway? And what happens when adult video starlets meet their fans in person? Essays that are also enthralling narrative adventures.",
    rating: 4.18,
    _authorID: "bae-26c791a7-fa81-5d86-95c5-4119e2fef915",
    _sellerID: "bae-81d5fadb-c2a3-5d95-b235-a220c220bf79"
  }) { _docID title }
  b33:add_Book(input: {
    title: "Girl with Curious Hair",
    genre: "Fiction",
    plot: "Remarkable and unsettling reimaginations of reality.",
    rating: 3.85,
    _authorID: "bae-26c791a7-fa81-5d86-95c5-4119e2fef915",
    _sellerID: "bae-81d5fadb-c2a3-5d95-b235-a220c220bf79"
  }) { _docID title }
  b41:add_Book(input: {
    title: "Les Misérables",
    genre: "Fiction",
    plot: "Victor Hugo's tale of injustice, heroism and love follows the fortunes of Jean Valjean, an escaped convict determined to put his criminal past behind him.",
    rating: 4.21,
    ratings: [3.9, 4.1],
    _authorID: "bae-4bfe5f4c-d668-5dc3-9de2-eb598af3da7d",
    _sellerID: "bae-81d5fadb-c2a3-5d95-b235-a220c220bf79"
  }) { _docID title }
}

Anatomy of a query block​

Syntax – Query block
{
  TYPE(
    filter: object, docID: [ID],
    order: [object],
    limit: int, offset: int,
    orderBy: [object]
  ) {
    [returnfield]
  }
}
  • TYPE – Name of the collection to query.
  • filter, docID – Criteria for documents to select, see Filter documents.
  • order – Results sorting fields, see Sort results.
  • limit, offset – Number of results to return/skip, see Limit and paginate results.
  • groupBy – Fields to group results by, see Group results.
  • [field] – List of fields to return for the selected documents. Queries return the exact fields requested (GraphQL has no equivalent of the SQL SELECT * syntax).
Example query – Filter books by genre and author's name; return 3 ordered by title
{
  Book(
    filter: {
      genre: { _eq: "Fiction" },
      author: { name: { _eq: "George Orwell" } }
    },
    limit: 3,
    order: { title: ASC }
  ) {
    title
    plot
    author {
      name
    }
  }
}

Run a query​

The basic skeleton of a query is made of the type/collection you want to fetch from (ex. Book) and the fields you want to return among the ones defined on the collection (ex. title, plot). _docID is a return field available available on any type.

Run a query via the CLI command defradb client query.

Retrieve all documents of type Book, returning docID, title, plot
defradb client query '
{
  Book {
    _docID
    title
    plot
  }
}
'
Result
{
  "data": {
    "Book": [
      {
        "_docID": "bae-526a42c6-c147-57e4-89e0-875d27a1532d",
        "plot": "A masterpiece of rebellion and imprisonment where war is peace, freedom is slavery, and Big Brother is watching.",
        "title": "1984"
      },
      {
        "_docID": "bae-8a6c163a-29cd-5607-a965-199487e58b00",
        "plot": "Victor Hugo's tale of injustice, heroism and love follows the fortunes of Jean Valjean, an escaped convict determined to put his criminal past behind him.",
        "title": "Les Misérables"
      },
      {
        "_docID": "bae-92465255-4869-5994-9898-83576ee9ff60",
        "plot": "The adventures of a penniless British writer among the down-and-outs of two great cities.",
        "title": "Down and Out in Paris and London"
      },
      {
        "_docID": "bae-9579541e-f15d-506e-a74a-63d00cb3ab56",
        "plot": "At the dawn of the next world war, a plane crashes on an uncharted island, stranding a group of schoolboys.",
        "title": "Lord of the Flies"
      },
      {
        "_docID": "bae-a3dad950-43cc-5f03-9b33-b61ebc936ac4",
        "plot": "Do lobsters feel pain? Did Franz Kafka have a funny bone? What is John Updike's deal, anyway? And what happens when adult video starlets meet their fans in person? Essays that are also enthralling narrative adventures.",
        "title": "Consider the Lobster and Other Essays"
      },
      {
        "_docID": "bae-c26135f1-59d6-5f32-a7c0-16dbec525abe",
        "plot": "A gargantuan, mind-altering tragi-comedy about the Pursuit of Happiness in America.",
        "title": "Infinite Jest"
      }
    ]
  }
}

Relationships​

If a document has a relationship to another document, the return fields can include the fields of the linked document. This applies both for one-to-one and to one-to-many relationships, and to both sides of the relationship.

Retrieve all persons and the titles of their authored books
{
  Person {
    authoredBooks {
      title
    }
    name
  }
}
Result
{
  "data": {
    "Person": [
      {
        "authoredBooks": [
          {
            "title": "1984"
          },
          {
            "title": "Down and Out in Paris and London"
          }
        ],
        "name": "George Orwell"
      },
      {
        "authoredBooks": [
          {
            "title": "Lord of the Flies"
          }
        ],
        "name": "William Golding"
      },
      {
        "authoredBooks": [
          {
            "title": "Infinite Jest"
          },
          {
            "title": "Consider the Lobster and Other Essays"
          },
          {
            "title": "Girl with Curious Hair"
          }
        ],
        "name": "David Foster Wallace"
      },
      {
        "authoredBooks": [
          {
            "title": "Les Misérables"
          }
        ],
        "name": "Victor Hugo"
      }
    ]
  }
}

You can walk connected types without boundaries: if type Person has a relationships with type Book, which has a relationship with type Company, you can query Person and return Person.Book.Company.<field>. The result will reflect the nested structure of the documents.

Retrieve all persons, their authored books, and the related sellers
{
  Person {
    authoredBooks {
      title
      seller {
        name
      }
    }
    name
  }
}
Result
{
  "data": {
    "Person": [
      {
        "authoredBooks": [
          {
            "seller": {
              "name": "The Independent Hipster Bookshop"
            },
            "title": "1984"
          },
          {
            "seller": {
              "name": "The Independent Hipster Bookshop"
            },
            "title": "Down and Out in Paris and London"
          }
        ],
        "name": "George Orwell"
      },
      {
        "authoredBooks": [
          {
            "seller": {
              "name": "The Independent Hipster Bookshop"
            },
            "title": "Lord of the Flies"
          }
        ],
        "name": "William Golding"
      },
      {
        "authoredBooks": [
          {
            "seller": {
              "name": "The World-Destroying Large Chain"
            },
            "title": "Infinite Jest"
          },
          {
            "seller": {
              "name": "The World-Destroying Large Chain"
            },
            "title": "Consider the Lobster and Other Essays"
          },
          {
            "seller": {
              "name": "The World-Destroying Large Chain"
            },
            "title": "Girl with Curious Hair"
          }
        ],
        "name": "David Foster Wallace"
      },
      {
        "authoredBooks": [
          {
            "seller": {
              "name": "The World-Destroying Large Chain"
            },
            "title": "Les Misérables"
          }
        ],
        "name": "Victor Hugo"
      }
    ]
  }
}

Get documents by ID​

Query the database for a specific document ID via the docID argument in the type constructor. You can query for one or more documents by providing either a string or a list of strings.

Get one author by ID and return his books
{
  Person(docID: "bae-bc532931-4843-50bc-bbdd-3e31549c8cc6") {
    name
    authoredBooks { title }
  }
}
Result
{
  "data": {
    "Person": [
      {
        "authoredBooks": [
          {
            "title": "1984"
          },
          {
            "title": "Down and Out in Paris and London"
          }
        ],
        "name": "George Orwell"
      }
    ]
  }
}
Get several authors by ID and return their books
{
  Person(
    docID: [
      "bae-bc532931-4843-50bc-bbdd-3e31549c8cc6",
      "bae-26c791a7-fa81-5d86-95c5-4119e2fef915"
    ]
  ) {
    name
    authoredBooks { title }
  }
}
Result
{
  "data": {
    "Person": [
      {
        "authoredBooks": [
          {
            "title": "1984"
          },
          {
            "title": "Down and Out in Paris and London"
          }
        ],
        "name": "George Orwell"
      },
      {
        "authoredBooks": [
          {
            "title": "Infinite Jest"
          },
          {
            "title": "Consider the Lobster and Other Essays"
          },
          {
            "title": "Girl with Curious Hair"
          }
        ],
        "name": "David Foster Wallace"
      }
    ]
  }
}
tip

If both filter and docID are given, both criteria must be fulfilled for a document to be selected.

Query the database
Edit this page