Skip to main content

Step 6: Querying entities

Most applications require the ability to query a dataset with filtering and ordering on the results. The CRUD API generated by ChiselStrike has these capabilities built in.

note

A filter is similar to a SQL WHERE clause, and ordering is similar to a SQL ORDER BY clause.

Here again is the BlogPost entity that you defined previously:

my-backend/models/BlogPost.ts
export class BlogPost extends ChiselEntity {
    author: string = "Anonymous"
    content: string
    publishedAt: number
    hidden: boolean
}

And here is the data set that resulted from following all of the instructions in the prior step:

  {
    "id": "[GENERATED-ID]",
    "author": "Dejan",
    "content": "...",
    "publishedAt": 777,
    "hidden": true
  },
  {
    "id": "[GENERATED-ID]",
    "author": "Glauber",
    "content": "...",
    "publishedAt": 999,
    "hidden": false
  },
  {
    "id": "[GENERATED-ID]",
    "author": "Pekka",
    "content": "...",
    "publishedAt": 888,
    "hidden": false
  }

Filter on a single entity property​

To query for only posts that were authored by "Glauber", you can use a filter on the author property:

curl "localhost:8080/dev/posts?.author=Glauber"
{
  "results": [
    {
      "id": "[GENERATED-ID]",
      "author": "Glauber",
      "content": "...",
      "publishedAt": 999,
      "hidden": false
    }
  ]
}

Note that you are still using the same base URL for BlogPost entities, but you are now adding a query string parameter to specify the filter. The name of the query string parameter is .<property>, where the name of the entity property is prefixed by a period character.

caution

When building query strings, you should always URL-encode properties and values so they are safe to insert into the query string. If you're using an HTTP client library to build the URL, it might do this for you automatically. In this tutorial, we will not have occasion to escape any keys or values for simplicity.

Filter on multiple entity properties​

You can specify multiple filters by combining them as mutiple query string parameters in the query string. Parameters are separated by an ampersand (&), and they are always combined using a logical-AND operation. To filter for posts authored by Glauber that are also not hidden:

curl "localhost:8080/dev/posts?.author=Glauber&.hidden=false"

This will yield the same matching entity from above. However, if you change the hidden filter to true:

curl "localhost:8080/dev/posts?.author=Glauber&.hidden=true"

You will receive no matching results:

{
  "results": []
}

Range filters​

You can query for ranges of values of a property by composing a parameter name that indicates what kind of comparison to perform.

To query for posts whose publishedAt property value is greater than 800:

curl "localhost:8080/dev/posts?.publishedAt~gt=800"

Note that the name of the filter parameter has ~gt appended to it. This is short for "greater than". ChiselStrike supports a number of filter options, including inequality, greater/less than, and string "like" (simliar to SQL LIKE). See the entire list in the reference documentation.

The above query yields results similar to this:

{
  "results": [
    {
      "id": "[GENERATED-ID]",
      "author": "Glauber",
      "content": "...",
      "publishedAt": 999,
      "hidden": false
    },
    {
      "id": "[GENERATED-ID]",
      "author": "Pekka",
      "content": "...",
      "publishedAt": 888,
      "hidden": false
    }
  ]
}