Search Queries

In the most general form, a Yesplan query consists of three parts:

scope:keyword:word

A few examples:

event:name:Othello: Search all events with ‘Othello’ in the name.
resource:role:sound engineer: Search all resources with a sound engineer role.

The scope of a query determines which type of element you will search in:

If you’re only looking for events, you use event as the scope, for resources you use resource etc.
The summary of scopes displays a list of all scopes that Yesplan supports.
A scope is always written in English even if you set the Yesplan language to a different language.

The keyword determines which property of an element you will query:

Some examples include name, location, date, label etc.
The summary of keywords displays a list of valid keywords that you can use in Yesplan and the scope in which they are applicable.
A keyword is always written in English, even if you set the Yesplan language to a different language.

The word is the last part of a query. This describes the textual value that you search for within the properties that you’ve indicated with the keyword:

The query resource:role:sound will search for all resources whose role contains the name ‘sound’.
The word you use in the query (e.g. ‘sound’) only has to be part of the effective value in Yesplan. The previous query will also result in all resources with a ‘sound engineer’ role.
The word isn’t case-sensitive: ‘jan’ gives the same results as ‘Jan’.

Simple Queries§

We will explain the concepts above based on a few examples.

Let’s take a look at the query below:

event:name:othello

The scope of this query is event, the keyword is name and the word is othello.

The result of this query will be a list of all events whose name contains ‘othello’. The word doesn’t have to match the value of the characteristic exactly, but it can be part of the value. In the example below, you see that events with the name ‘Othello’, ‘Othello 1’, ‘Othello 2’ and ‘Othello 3’ appear as results. This rule applies to most keywords in which the desired property is a name or a piece of text such as name. For keywords in which the desired property is a date or a number, the match will have to be exact.

A word can’t contain spaces. If you want to add spaces anyway, you can do so by adding double quotation marks ("…") around the words, for instance:

group:name:"The Film Festival"

The result of this query will contain the event group with the name ‘The Film Festival’.

In addition to spaces, a word can’t contain the following symbols: * # : ( ). These symbols are part of the syntax of the query language, as will become clear in a moment. If you want to include one of these symbols in a word after all, you must use double quotation marks.

If the type of element that you want to look up isn’t important, you can omit the scope of a query in the search. Let us assume that you want to search for all elements in Yesplan that have a ‘rental’ label. You can achieve this with the following query:

label:rental

The result is a list of different types of elements, e.g. an event, a resource and a contact. You’ll find a full summary of keywords that allow this under keywords with default scopes.

Finally, it’s also possible to omit the keyword in a query and only enter a word. In that case, the query language will search all elements in Yesplan whose name contains the word.

For example:

othe

The result of this query will show the events ‘Othello’, ‘Othello 1’, ‘Othello 2’, ‘Othello 3’, as well as the event group ‘Othello Production’.

Tip

If you want to find an event by Yesplan ID, you must always use the keyword:

id:3046435073-1631780039

The search query below won’t yield any results:

3046435073-1631780039

Absence of Values§

A special case in the query language is an empty word with quotation marks around it (""). If you use this, then the absence of a value for the keyword will be checked. The query below will request all people who don’t have a label.

person:label:""

You can only check for the absence of a value for fields where the keyword is applicable. Under resources, for example, the keyword team is only applicable on resources of type “Human” because only such resources can be part of a team. The query below requests all resources in which the team keyword is applicable, but no value is present. The result is all resources of type “Human” that aren’t part of a team. Resources of other types won’t appear in the results.

resource:team:""

If you need an overview of the events that don’t have a location, you can use the following query:

event:location:""

Please take into account that event groups behave differently:

group:location:""
group:location:theater

The first query will only return event groups where none of the events have a location. The second query will only return the event groups where at least one event takes place in the theater.

Using a Wildcard§

To indicate that it doesn’t matter what the value of a certain property is, you can use a so-called wildcard, that you write as an asterisk (*). The wildcard works like the reverse of an empty word ("") and it checks the presence of a value.

The query below requests all resources of any type:

resource:type:*

When you use a wildcard as a word, only those results appear that have a value for the keyword that you entered.

For example, let’s take a look at the query below:

person:label:*

This query will request all people who have a label. People without a label won’t appear.

If a keyword isn’t applicable, it can’t have a value. The query below requests all resources that are part of a team. These will always be resources of type “Human”: the keyword team is only applicable on such resources because only they can be part of a team.

resource:team:*

You can also use the wildcard as a keyword. The query below will request all contacts for which any property contains the value ‘jan’.

contact:*:jan

Using Dates and Periods§

The query language offers extensive functionality to ask questions in which the desired property is a certain date or falls in a certain period.

Exact Date§

For dates, you can search for an exact match with a certain date. You enter dates in the format dd-mm-yyyy (“Day Month Year”). The query below will request all events that take place on 28 March 2013.

event:date:28-03-2013

Remark

For keywords where the desired property is a date, different rules apply for finding a match than for textual property. For textual characteristics, there is a match if the value of the property contains the entered word. The match will be exact for dates.
The date format selected for Yesplan in the system settings doesn’t have any impact on the date format in the query language. You must use the format dd-mm-yyyy in the query language (i.e. ‘28-03-2013’ for 28 March 2013), even if the format “Month Day Year” has been selected in the system settings.

Range§

The query language also allows you to use a range as a word:

Note a range by using two dates that are separated by TO.
You need to separate the dates from TO with a space.
There is a match if the date falls within the entered range.

For example, we can request all events from 15 March through 30 March 2013 using the query below:

event:date:15-03-2013 TO 30-03-2013

Moreover, you can search within a period on or after a specific date with the keyword dateafter. That way, for example, we can query all events on or after 15 March:

event:dateafter:15-03-2013

Dynamic Dates§

In addition to searching by a specific date, or for a specific range, the query language also offers a number of dynamic dates.

For example:

event:date:#today

This query uses the word #today to limit the request to all events that take place today. You will find similar words in the table below:

Word	Description
`#tomorrow`	The date matches tomorrow.
`#yesterday`	The date matches yesterday.
`#thisweek`	The date falls in the current calendar week. This is the week that starts on the most recent Monday and runs through the next Sunday.
`#previousweek`	The date falls in the previous calendar week. This is the week that ends before the most recent Monday.
`#nextweek`	The date falls in the next calendar week. This is the week that begins after the next Sunday.
`#thismonth`	The date falls in the current calendar month.
`#previousmonth`	The date falls in the previous calendar month.
`#nextmonth`	The date falls in the next calendar month.
`#thisyear`	The date falls within the current calendar year.
`#previousyear`	The date falls within the previous calendar year.
`#nextyear`	The date falls within the next calendar year.
`#nextXdays`	The date falls in the X number of calendar days after today. `#next1days` is the same as `#tomorrow`.
`#previousXdays`	The date falls in the X number of calendar days preceding today. `#previous1days` is the same as `#yesterday`.
`#nextXweeks`	The date falls in the X number of calendar weeks following the current calendar week. `#next1weeks` is the same as `#nextweek`.
`#previousXweeks`	The date falls in the X number of calendar weeks preceding the current calendar week. `#previous1weeks` is the same as `#previousweek`.
`#nextXmonths`	The date falls in the X number of calendar months following the current calendar month. `#next1months` is the same as `#nextmonth`.
`#previousXmonths`	The date falls in the X number of calendar months preceding the current calendar month. `#previous1months` is the same as `#previousmonth`.
`#nextXyears`	The date falls in the X number of calendar years following the current calendar year. `#next1years` is the same as `#nextyear`.
`#previousXyears`	The date falls in the X number of calendar years preceding the current calendar year. `#previous1years` is the same as `#previousyear`.

Remark

For the #nextX… and #previousX… keywords, you must replace the X with a number. event:date:#nextXdays won’t work, event:date:#next7days will.

Requesting Custom Data§

With the query language, we can also search for Yesplan elements based on their custom data fields. To do this, you must use the custom data field keyword as a keyword in the query. In Yesplan, you can have the keywords for custom data fields generated automatically or you can set them manually.

Tip

See the section Keyword for more information about setting keywords automatically or manually in the system settings.

In the example below, you see a custom data field with the label ‘Manager’, which automatically receives the keyword ‘production_info_manager’.

Then you can request all resources where the ‘Manager’ is ‘Sarah Peeters’ with the following query:

resource:production_info_manager:"Sarah Peeters"

Tip

You can retrieve the keyword for custom data fields easily in an inspector by holding down Ctrl+Alt (Windows) or Ctrl+Option (macOS). The field’s label will change to the keyword.
If you want to copy the keyword, then click the label while holding down these keys.

The picture below shows a custom data field definition with the label ‘Operator’ to which the administrator assigned the keyword ‘operator’.

You can then request all resource bookings for which the custom data field has the value ‘Jan Janssens’, using the following query:

resourcebooking:operator:"Jan Janssens"

Remark

When you manually set a keyword for a custom data field, you can’t use the automatically generated keyword in the query language for that field:

The query resourcebooking:production_info_operator:"Jan Janssens" will no longer work if the keyword ‘operator’ has been assigned to that field.
However, you can use resourcebooking:operator:"Jan Janssens".

When searching for a Yes/No field, you must enter the value in English. Use the values yes, no, true or false. For example, if you want to request a custom data field to search for damaged resources, you can use the following query:

resource:properties_state_damaged:yes

Finally, you can also search for the publication status of an event in the ticketing integration:

event:publicationtrigger-keyword:active: Show all Yesplan events that are linked with the integration.
event:publicationtrigger-keyword:"": Display all Yesplan events that aren’t linked with an integration.
event:publicationtrigger-keyword:error: Search for all Yesplan events where an error occurred when linking with the integration.

Requesting Numeric Fields§

For keywords where the desired property is a number, different rules apply for finding a match than for textual properties.

For textual properties, there is a match if the value of the property contains the entered word. For example, the query event:name:othello will find an event named ‘Othello’ as well as an event named ‘Othello 2’.

For numbers, there is a match if the value matches exactly. For example, if ‘free_seats’ is the keyword of a numeric custom data field, the result of the query event:free_seats:23 will only find events for which the value of the custom data field is exactly ‘23’ and not events where the value of the custom data field is ‘123’ or ‘234’.

This exact match isn’t valid for regular input fields where you (sometimes or always) enter a number. A numeric input field is a specific type of custom data field.

Requesting Addresses of Contacts§

A contact can have one or more addresses. Each of these addresses is of a certain address type. Per contact, there is always one address marked as default, the default address. You can manage address types in system settings.

The keywords address, street, zip, city, country and country code always request the default address. The query language also foresees keywords for all the different types of addresses that a contact can have. You form these variants by the default keyword, preceded by the name of the address type and an _ (underscore).

For example, for the ‘Billing’ address type, the keywords are billing_address, billing_street, billing_zip, billing_city, billing_country and billing_countrycode.

Please note: when composing the keyword, the same rules apply as for the automatic assignment of keywords for custom data fields: spaces and special characters (such as ! ? ; etc.) are deleted and capital letters are converted to lowercase letters. An administrator can find the keyword in “System Settings” > “Contacts” > “Address Types”.

For example, for the ‘Headquarters’ address type the keywords are headquarters_address, headquarters_zip etc.

The variants of the keywords always request the address of a certain address type, whether this address is marked as the default address or not.

For example, with the query contact:city:Gent you search for all contacts whose city contains ‘Gent’ in the default address. With the query contact:billing_city:Gent you search for all contacts whose city contains ‘Gent’ in the ‘Billing’ type of address.