Core Docs - Core Concepts - Use Entity Search

Rock Version: v19.0
Last Modified: 2026-03-24 9:16 AM

Entity Search makes querying Rock feel less like writing code and more like getting answers. With just a few simple expressions, you can refine and fetch exactly the data you need, right when you need it.

When you're building custom tools, Entity Search gives you a flexible way to work with Rock records—no SQL required. You can use the Searches you write with API v2 or even Entity Commands in Lava. We'll explore both options in a bit.

To add an Entity Search, navigate to Admin Tools > Settings > Entity Search.

To add a new Entity Search, press ti ti-plus.

Make sure to click Save once you are done, and you have a Search that is ready for API v2 usage!

Our Entity Search uses Language Integrated Queries—also known as LINQ—a way to query data in the programming language C#. Read this article for more on how to use LINQ on our Dynamic LINQ syntax.

If your expression is accurate, it will display JSON data when you select ti ti-search.

When you create a search query, you can configure its security by pressing ti ti-lock.

By default, only View permissions are given to all users. To use this query in an API call or Entity Search, you must give Execute permissions.

Reuse Searches with Entity Search
Define your search once using Entity Search and reuse it across Rock with the entitysearch parameter. It keeps your Lava cleaner, your logic centralized, and your filters consistent. You can still customize results with expressions or parameters like groupby, select, and sort.  

For more on using an Entity Search query with Lava, see the Lava Docs on Entity Commands.

Extend Entity Search with Payloads

Once you've created an Entity Search in Rock, you've built a reusable query that refines and retrieves data. But sometimes, the built-in UI options don't give you quite enough flexibility.

That's where payloads come in.

A payload is a block of JSON you can attach to a request to customize how your Entity Search behaves. Instead of replacing your query, the payload lets you refine, override, or extend it—just for that specific use case.

Example: Simple Filter and Select

{
  "where": "id < 10",
  "select": "new (Id, Guid, Name, GroupType.Name as Type)",
  "order": "id, name desc, type.name",
  "skip": 2,
  "take": 1
}

{
  "id": 2,
  "guid": "628c51a8-4613-43ed-a18d-4a6fb999273e",
  "name": "RSR - Rock Administration",
  "type": "Security Role"
}

Example: Group and Count

{
  "where": "GroupTypeId == 1 || GroupTypeId == 10",
  "groupby": "new (GroupTypeId, GroupType.Name)",
  "select": "new { Key.GroupTypeId, Key.Name, Count() as Total }",
  "order": "Total desc",
  "skip": 0,
  "take": 10
}

What it does:

{
  "count": 2,
  "items": [
    {
      "groupTypeId": 1,
      "name": "Security Role",
      "total": 25
    },
    {
      "groupTypeId": 10,
      "name": "Family",
      "total": 42
    }
  ]
}

Unique Payload Properties:

Use Entity Search With the v2 API

You can find all entities with available REST endpoints in the API v2 Docs, located at Admin Tools > Settings > API v2 Docs. These endpoints can be used with your custom code.

To try an operation that uses a SearchKey—such as a GET or POST—this is what you will do:

Match Your Endpoint and Entity
Be sure the endpoint you’re using exactly matches the Entity Type you set when configuring Entity Search. A mismatch here can cause unexpected results.