Queries ​

Sometimes, we need to find specific information within our Capacities content.

Queries allow you to collect content based on rules

Think of queries as a way to look at your content from a different perspective. You can use queries to find specific information within your content, save it, and reuse it elsewhere.

You can also think of queries as automated collections or pools of content. As soon as you create new content that matches the rules of a query, it will automatically be added to the query. Queries automatically organize your content for you.

Examples of queries are:

• All objects that are tagged with #todo and #important

• All content that includes the word knowledge and was created in the last seven days

• All projects and meetings with my colleague John

Queries are a powerful feature; they let you retrieve specific pieces of information from within your objects, be it from the properties, the title or the blocks. You can save these queries as objects to reuse, too.

You can currently create three different types of queries that extend the functions you're already used to using.

Overview ​

Queries are not a fundamentally new concept, but they extend the functions you're already used to using.

There are three different types of queries:

• Object type queries Object type queries return content based on a set of object types and optional filters. You can apply rules based on collections, tags, and properties. Object type queries extend your object dashboard.

• Search queries Search queries return content based on a set of search terms. You can apply rules based on object types, properties, or tags to narrow down your results. Search queries extend the extended search.

• Tag queries Tag queries return content that is tagged by a set of tags. You can apply rules based on object types, properties, or other tags to narrow down your results. Tag queries extend tag pages.

If you want to get a quick overview of queries, check out this video:

Getting started with queries ​

You can create queries from these places (more on this below) or you can create a query from scratch. Queries are objects just like everything else in Capacities, so you can create queries in the same way you create other new objects too:

1. Click the + New button block in the top left of the window, choose "query"
2. Or open an object type, click the three dots and click "new query"
3. You can use Cmd/Ctrl + U and type query
4. You can also use the command palette (Cmd/Ctrl + K or Cmd/Ctrl + P) and type query and press Enter
5. In an object, type /query. This will embed the result of the query in the page straight away.

Once you've got the query ready to begin, you need to choose which type of query you need. The different types are broken down in more depth below, including examples to show when you might use each one.

Object type queries ​

Object type queries are great if you want to find specific objects based on strict rules, such as the properties they have or the tags they have.

In the object dashboard of your object types, you can filter and sort the objects by their properties in order to find specific selections of the objects of that type. With queries, you can now save these filters as a query and extend these rules beyond one object.

When you click Save as query your new query appears as a tab in the dashboard and is available in the left-hand sidebar. The example below shows a query looking for all quote objects where the favorite box is checked.

You can open the query as a page and give it a title. To reuse the query, you just need to link to it as you do other objects with @ or [[]]. Here, the favorite quote query is embedded in this 'Home' page.

Another example would be to see all meetings that are part of a project. This query looks for all meeting objects where the project includes "launch new product", and it's sorted in order of the dates the meeting took place. Once set up, you can embed this query into the project page.

Queries are also set up to be very easily adapted simply by opening the query as a full page and clicking 'edit' in the top right of the query object.

Create your own object type query ​

Now you know what you could do with a query, let's talk about how you can create one.

The specific things you can query depend on how your object types are set up. With object type queries, you're looking at the structure of your objects, essentially the properties you've assigned to them, their titles, and their types.

This is why you first choose the object types you'd like to search from the drop-down menu. You can choose up to 10 object types to include, and you can be more specific than that too, either including or excluding collections of these object types.

Then you decide if you're searching for objects with specific tags or if the information is in the properties. In the examples above, we were searching for properties (the favorite box and project name are all communicated via a property in their respective object types).

On top of these filters, you can choose if you want to add sorts, group the results by object type, or limit how many results you have.

Once you have configured the query you'd like, click Create.

Then, you can give the query a title, and that allows you to easily search for it later to link to it on other pages.

If you want to learn more about how to use object queries, check out this video:

Search queries ​

Search queries are great if you want to find specific objects based on a search term or a fuzzy topic. They build on the extended search and the command palette.

Extended search lets you search one term, add certain parameters and then review all these results in its own window. You can save any of these searches with the query function, which means you can easily search the same parameters again or embed this search in a different object.

Search queries let you see everything related to a topic, not just things you've linked or tagged.

Because search queries and extended search are so related, you can simply open the extended search by pressing Cmd + Shift + P (Mac) or Ctrl + Shift + P(Windows), define your search parameters, and click 'save as query' when you're done.

When you've saved it, you can embed this search in any relevant pages.

If you want to learn more about how to use search queries, check out this video:

Tag queries ​

With tag queries, you can now display the results of multiple tags and apply the same filters as other query types to refine the search further.

Below, there are three tags combined into one page to review related concepts.

To create a tag query, you can navigate to any tag object and click Create query with tag. From here, you can add more tags to the results and add any filters/views that you'd like. Don't forget to give it a title so you can reference it on other pages.

If you want to learn more about how to use tag queries, check out this video:

Queries in detail ​

All queries can be adjusted and fine-tuned to your needs. You can add more filters, change the sort, or limit the results. Let's look at these options in more detail.

Show objects or blocks ​

In tag and search queries, you can choose to only see text blocks or objects to narrow down your results. This is useful if you want to see all the text snippets that match your search term or tag.

Filter by tags ​

When tags are an extra bit of information, rather than the singular thing you're searching for, you might choose to filter by tags. If tags are the focus of your search, though, use tag queries.

Sort ​

Sorting chooses the order in which you see the results. Depending on the type of query you've chosen, you can sort by properties you have created or by properties Capacities creates, such as Created at.

Group by type ​

If you're bringing multiple object types into your query results, it might be easier to review the results if they are grouped by type. You can choose to do this by selecting Group by type in the query editor.

Limit Results ​

You might not want to see all the results for a query as you might expect a lot of results. In this case, you can limit the number of results you see.

Randomizing results ​

When choosing to limit your results, you can also choose to return a random list of results. This is great to get inspired by a large pool of content. You could, for example, create a query that returns five random quotes from all your quotes.

Reusing and embedding queries ​

Queries are set up to be used multiple times – they are objects like any other content. By saving queries and naming them sensibly, you can reuse them across your space very easily. You can embed them in any object with blocks with the @ or [[ ]] action, which is used everywhere else, and you can choose how to view them.

You can pin queries to your space (like an object) but also to your object dashboard for easy access. These will be in the left-hand sidebar with your object type list.

They will also be visible in your Object dashboards.

If you want to see different use cases for queries, check out this video:

What's next for Queries? ​

Queries are a powerful feature, and we're excited to see how you use them. We're also excited to see how we can extend them in the future. Here are some ideas we're thinking about:

• AI-powered search queries

  Queries that return content based on their semantic meaning. You can, for example, search for "Notes about Artificial Intelligence" and it will return content on neural networks or LLMs.

• Time-based queries

  Create queries based on a time span. You can, for example, return all objects and blocks that reference this week or a historic time period.

• Faceted search queries

  Show simple options to narrow down search results based on the current results. If results contain a lot of Quotes, allow to quickly filter for Quotes.

• Reference and Variable Queries

  Create queries with filters based on the current context as a variable. For example, on a Project page, embed a query of Meetings with a Project property of that specific project. Variables are based on the parent's properties.

• Rollup Queries

  Create queries that roll up content from other queries. For example, you can show all ingredients in your recipes that are tagged with #vegetarian and #italian.