M-Files BD – Queries: objectType, class, filters, date tokens

In the previous posts of this series, I covered the anatomy of a dashboard definition and the seven widget types (KPI & gauge, line & area, donut, bar & table) the engine supports, as of now. In this one, we will go through the Business Dashboard queries, i.e. the query section that I pretty much ignores so far. It is now time to look at it a bit more.

A query has four parts: objectType, class, filters, and aggregation. This post covers the first three. The fourth (aggregations, including its reducers) is the topic of the next post.

As mentioned before, the principle that drove the design of the Business Dashboard is to be generic. The engine never enumerates specific business values, it only translates the structured JSON query into a standard M-Files server search.

1. objectType – the M-Files object type to query

Every query starts with objectType. It is the M-Files object type the engine searches against, addressed by its display name (the singular form is fine, the engine resolves it and uses it).

1.1. Single object type

The simplest form is a string:

"objectType": "Document"

Or any other object type defined in your vault:

// Looking for Customers
"objectType": "Customer"

// Looking for Projects
"objectType": "Project"

// Looking for Employees
"objectType": "Employee"

The display name is case-insensitive but must otherwise match what the vault shows. Please note that, if the vault is let’s say, in German, you might need to use “Dokument” and not “Document”. In short, you need to use what the vault defines/shows.

If the name does not match, the widget shows a clear ✗ Object type ‘xxx’ not found in this vault error.

1.2. Multiple object types

When the same logical entity exists across more than one M-Files object type (for example, a “Proposal” can be both a Document and a Document collection), you can pass an array:

"objectType": ["Document", "Document collection"]

The engine resolves every name and builds a single search to find all matching objects. This behaves like the “is one of” filter in M-Files Advanced Search. Please note that the Drill-through will also inherit the same scope, automatically.

A small but important detail: even in this case, the engine executes a single search. This matters for performance and for consistency (a single serverScanMaxResults cap applies, not two independent caps).

2. class – narrowing the scope (and the perf impact)

The class field is optional but strongly recommended. It restricts the query to one specific class:

"objectType": "Document",
"class": "Contract or Agreement"

Querying “all Documents” in a vault that contains 50’000 documents of which only 1’000 are Contracts is pure waste. Adding “class”: “Contract or Agreement” narrows the scan immediately, which both improves performance and makes the widget result more meaningful.

Therefore, both M-Files Administrators and M-Files Users will thank you for selecting the right class to use. It avoids slowness, irrelevant results and reduces resource usage. You should always set a class, when possible.

When objectType is an array and class is specified, the engine will find any object, from that class, from any of the object types listed. So the following will match Proposal-class objects from both types:

"objectType": ["Document", "Document collection"],
"class": "Proposal"

If the class is misspelled, the widget shows a ✗ Class ‘xxx’ not found on the specified object type(s) error. As with object types, the name depends on what the vault defines/shows.

3. filters – the AND-combined conditions

The filters array, which is optional, contains zero or more conditions. If you specify multiple filters, then all filters must match. That means that M-Files applies a AND semantic between each filter. By the way, M-Files doesn’t directly support “OR” conditions, it always joins them. The only “kind-of-an-exception”, as far as I know, is the “is one of” where you can set multiple values from the Lookup/MultiSelectLookup property values. But that’s only a single condition, not multiple conditions.

Here is an example of a filter:

"filters": [
  { "property": "Effective through", "operator": "greaterOrEqual",
    "value": "@today", "valueType": "dateToken" },
  { "property": "Agreement type", "operator": "equals",
    "value": "Subcontracting Agreement" }
]

Each filter has up to four fields:

• property: the property display name on which to apply the operator / value.
• operator: one of the operators listed in section 4 below.
• value: the value to use for the comparison with the property’s actual value. For the four “presence” operators (isEmpty, isNotEmpty, isPresentEmpty, isPresentNotEmpty), this parameter should NOT be defined. For the “begin-end” operators (between / notBetween, this parameter should be an array of two elements. For the “is one of” operators (inList / notInList), this parameter should be an array of at least two elements. Finally, in all other cases, it’s simply a string.
• valueType: either “literal” (default, it means to use the value as-is) or a “dateToken” (covered in section 5).

4. The filter operators

The engine supports a rich set of operators across two execution paths:

• Native: runs server-side before the serverScanMaxResults cap is applied. Therefore, this is the preferred option, when possible.
• Post-filter: runs in memory after the server returns up to serverScanMaxResults objects. Therefore, this is correct and useful when you want to do something that M-Files doesn’t support out-of-the-box but that still makes sense for your Business use-case.

In short, whenever possible, prefer to apply a native filter. The main reason for this is simple. Let’s assume that you have 1’000 Contracts in the vault:

• If you apply a native filter, for example Effective through >= @today, then if only 200 of them match that criteria, then M-Files will only return these 200 objects directly. There is no loss of performance here.
• If you apply a post-filter, for example Effective through contains 2026-12, then M-Files will have no other choice than returning all 1’000 Contracts first. On top of that, the post-filter compares the value of Effective through and checks whether it contains “2026-12”. This is because the “contains” condition doesn’t exist in M-Files for Date properties. Therefore, we cannot use what doesn’t exist, but we still want to provide that possibility / logic, and therefore it is done in memory after returning all results. In that example, you get 5x more results and on top of it, you also need to check which ones match the expected value.

The performance difference between native and post-filter is imperceptible for small result sets (<few hundreds), but you would probably feel it if you expect to fetch thousands of results. A great catch, if you need to apply a post-filter for a valid business reasons, is to first apply a native one, which highly reduces the result set, and then apply the post-filter one that you need. Also, don’t forget to specify a class!

Then, let’s proceed with a deep-dive on the different operators (if you only want the “summary”, look at the end of section 4 for the cheat sheet). The 22 operators support all data types, without exceptions, contrary to M-Files operators which offer much less capabilities. The only distinction is, as mentioned above, whether the operator is native or post-filter.

4.1. equals and notEqual

As you would expect, these are for exact match. Only the MultiLineText properties are processed as post-filter.

{ "property": "Agreement type", "operator": "equals",
  "value": "Subcontracting Agreement" }

{ "property": "Customer", "operator": "notEqual",
  "value": "ESTT Corporation (IT)" }

When using display names on Lookup properties (Lookup or MultiSelectLookup), as its the case in above example, the value lists are cached, so that each execution doesn’t need to re-fetch the things that it already knows of, and it can just use it directly, to ask M-Files what’s the updated count.

4.2. lessThan, greaterThan, lessOrEqual, greaterOrEqual

These “range” operators support all property types except Boolean, because it doesn’t make any sense to apply a “lessThan” to a Boolean… In addition, and similarly to above, only the MultiLineText properties are processed as post-filter, everything else is native. Obviously, you can apply these operators on Date and Numeric values, but it also works with Text, Lookup or MultiSelectLookup. When it needs to work on Text-based properties, it does a lexicographic comparison (e.g. ABC < ABD, ACE > ABB).

{ "property": "Due date", "operator": "lessThan",
  "value": "@today", "valueType": "dateToken" }

{ "property": "Amount", "operator": "greaterOrEqual", "value": 1000 }

4.3. between and notBetween

These as also “range” operators but I put them separately because the value must be a two-element array, as previously written. between is, otherwise, exactly the same as lessThan/greaterThan/lessOrEqual/greaterOrEqual. In the array, you would provide the begin and the end of the range. to fetch.

{ "property": "Effective through", "operator": "between",
  "value": ["@startOfYear", "@endOfYear"], "valueType": "dateToken" }

{ "property": "Amount", "operator": "between", "value": [100, 1000] }

notBetween is the opposite of between, obviously, but it’s a bit more than that… As previously mentioned, M-Files does NOT handle OR logic. But if you think about it, a “notBetween” is actually an OR, because you want values below the range OR above the range (value < low OR value > high). Because of that, notBetween is always a post-filter, without exception.

{ "property": "Amount", "operator": "notBetween", "value": [100, 1000] }

4.4. isEmpty, isNotEmpty, isPresentEmpty, isPresentNotEmpty

These four operators test whether a property has a value, as the name suggests… However, there is a catch: M-Files only distinguish between “the property is present and empty” or “the property is present and non-empty”.

You might have faced that with Templates for example. That’s a pretty common occurrence. In M-Files, there is a parameter “Is template” which indicates whether a specific object has been defined as a template. But that parameter is only present in a few select objects, it’s usualy not present on all of them. Therefore, if you search for “Is template – is empty”, you will most probably find 0 results, because M-Files only check for documents where the property is present and where it is empty.

The distinction is simple but it matters a lot. That’s why in the Business Dashboard, the native M-Files “is empty” / “is not empty” have been renamed as isPresentEmpty and isPresentNotEmpty. These are the fully native option from M-Files, and therefore they run on the server-side.

{ "property": "Effective through", "operator": "isPresentEmpty" }

{ "property": "Responsible person", "operator": "isPresentNotEmpty" }

In addition, I also defined two other operators, isEmpty and isNotEmpty. These two are always post-filters, they scan all matching objects in memory after the server returns them:

{ "property": "Effective through", "operator": "isEmpty" }

{ "property": "Responsible person", "operator": "isNotEmpty" }

Because of that post-processing, isEmpty matches objects where the property is absent OR where it is present but empty. This allows a more “complete” result set, which might be required in some specific business use-cases.

isNotEmpty matches objects where the property is present AND non-empty. You might think it is exactly the same as isPresentNotEmpty, right? Well, in 99% of the cases, yes it is the same (but slower, since done as post-filter)… Except when there are bugs in M-Files ;). While developing the Business Dashboard, I found a few bugs, including one with lexicographic processing on MultiSelectLookup properties. The usage of my own operator was giving me a slightly different result and while investigating why, I found the reason and the bug in M-Files’s own operator.

In summary:

4.5. inList and notInList

As the name suggests, if you are looking for multiple values, inList is what you should use. It must be an array of at least 2 elements, but you can put 50 if you want to. M-Files only support Lookup for this one, natively. Therefore, all other property types are handled as post-filters.

{ "property": "Agreement type", "operator": "inList",
  "value": ["Subcontracting Agreement", "Project Agreement"] }

{ "property": "Workflow state", "operator": "inList",
  "value": ["In review"] }

notInList is simply the opposite, so it just excludes all elements provided. It supports exactly the same thing as inList and works in the same way too.

{ "property": "Workflow state", "operator": "notInList",
  "value": ["Approved"] }

A subtle catch with “not” operators (notInList and similar): an object whose Lookup property is present but has no item selected satisfies “not in list” by default, because there is no value to match or compare with. If you don’t want to see these objects, then you can simply add a second filter on that same property with isPresentNotEmpty!

4.6. contains and doesNotContain

contains is a substring match (similar to matchesWildcardPattern (c.f. below) with implicit wildcards on both sides), it finds objects where the property value includes the given string anywhere inside.

{ "property": "Title", "operator": "contains", "value": "NDA" }

{ "property": "Title", "operator": "doesNotContain",
  "value": "draft" }

For Text, MultiLineText and Lookup properties, both operators are native. The rest is supported as post-filters, comparing against the string representation.

4.7. startsWith, doesNotStartWith, endsWith, doesNotEndWith

startsWith and doesNotStartWith match objects based on the beginning of a property’s value. These are native only for Text and Lookup properties.

{ "property": "Name or title", "operator": "startsWith",
  "value": "PO-"    }

{ "property": "Name or title", "operator": "doesNotStartWith",
  "value": "DRAFT-" }

endsWith and doesNotEndWith match based on the end of a property’s value. This doesn’t exist in M-Files, there is no equivalent and therefore, these are always post-filters for all property types.

{ "property": "Name or title", "operator": "endsWith",
  "value": "(final)" }

{ "property": "Name or title", "operator": "doesNotEndWith",
  "value": "(draft)" }

4.8. matchesWildcardPattern and doesNotMatchWildcardPattern

These are the most expressive pattern operators. The value is a regex string where \* matches any number of characters and ? matches exactly one character. This is pretty similar to the contains/startsWith/endsWith (and their opposite), obviously, but it is a bit more powerful if you need to match an exact pattern that you know of.

{ "property": "Title", "operator": "matchesWildcardPattern",
  "value": "PO-????-2026" }

{ "property": "Title", "operator": "doesNotMatchWildcardPattern",
  "value": "ID-*" }

4.9. Complete operator reference

You reached this point, so it’s time to have a cheat sheet of all operators. In the below table:

• Text and MultiLineText are NOT interchangeable
• “Lookup” includes both Lookup and MultiSelectLookup (these ARE interchangeable – one exception for between on MultiSelectLookup because of a bug in M-Files – the one I mentioned above)
• “Date” includes Date, Time and Timestamp (these ARE interchangeable – one exception for notEqual on Timestamp because of a bug in M-Files – not the same as the one mentioned above)
• “Numeric” includes Integer, Integer64 and Floating (these ARE interchangeable) (“integer”/”real”)

4.10. Pattern operators on date properties

All pattern operators (contains, startsWith, endsWith, matchesWildcardPattern and their negations) work on date properties via the post-filter path, comparing against the ISO yyyy-MM-dd string representation (or yyyy-MM-dd HH:mm for timestamp or HH:mm:ss for time properties). This opens up some convenient patterns, even with “valueType”: “literal”:

{ "property": "Effective through", "operator": "startsWith",
  "value": "2026" }

{ "property": "Effective through", "operator": "startsWith",
  "value": "2026-04" }

{ "property": "Effective through", "operator": "endsWith",
  "value": "-31" }

{ "property": "Effective through", "operator": "matchesWildcardPattern",
  "value": "2026-??-??" }

And with “valueType”: “dateToken”, the token resolves to a full ISO date used as the exact string pattern:

{ "property": "Effective through", "operator": "contains",
  "value": "@today", "valueType": "dateToken" }

{ "property": "Effective through", "operator": "startsWith",
  "value": "@startOfMonth+5d", "valueType": "dateToken" }

A resolved token produces a full ISO date for the operators, c.f. next section for a deeper dive into dateToken details.

5. Date tokens – relative filters that always make sense

Hardcoding a date like “2026-01-01” in a filter works, but it ages badly. The dashboard built today shows different data on January 2nd than it did on December 31st, because the filter is now relative to a different “today”.

Date tokens solve this. Any string value used with “valueType”: “dateToken” is resolved to an absolute date at query execution time, so the dashboard stays meaningful as time passes.

5.1. Anchor tokens

The following anchors are recognized:

So @startOfYear, at the time of writing this blog (i.e. in 2026) is 2026-01-01 00:00:00. Starting from January 1st 2027, the same token will automatically resolve to 2027-01-01 00:00:00 instead. Therefore, the dashboard rolls forward automatically.

If there is a need to add more date tokens, it’s always possible.

5.2. Offsets: days, hours, minutes, and seconds

Any anchor presented above can be followed by one or more offsets to add or subtract time:

Each offset uses d for days, h for hours, m for minutes, and s for seconds. As you can see above, offsets can be chained together in any order, so @today+2d+10h+30m is valid, as is @now-8h+30m.

The day offset is calendar days, not business days. There is no built-in concept of holidays in the engine as of now.

5.3. Fixed ISO dates (with optional offset)

A literal ISO date works as both literal as well as a date token. However, if you want to apply an offset, then only dateToken can be used. As previously mentioned, “literal” really means a literal strings, so there is no computation done on it.

{ "property": "Effective through", "operator": "greaterOrEqual",
  "value": "2026-01-01+90d", "valueType": "dateToken" }

This resolves to 2026-04-01 00:00:00, at query time. This can be useful when you want a stable absolute anchor but with an offset relative to it.

5.3a. When to use @now instead of @today

The key difference between @now and @today is that @now captures the current time including hours, minutes, and seconds, while @today is truncated to midnight.

Use @today for day-level filters (most common): “contracts expiring within 30 days”, “documents created this month”. Use @now when you need intra-day precision: “events logged in the last 2 hours”, “tasks to process in next 4 hours”. Examples:

// All activity since this morning at 7am (a fixed time each day)
{ "property": "Modified", "operator": "greaterOrEqual",
  "value": "@today+7h", "valueType": "dateToken" }

// Flagged tasks created in the last 8 hours
{ "property": "Created", "operator": "greaterOrEqual",
  "value": "@now-8h", "valueType": "dateToken" }

6. Boolean filter values

For boolean-typed properties (M-Files “Boolean (yes/no)”), the engine accepts both “Yes” / “No” and “True” / “False” (case-insensitive):

{ "property": "Accepted", "operator": "equals",
  "value": "Yes" }

{ "property": "Accepted", "operator": "equals",
  "value": "True" }

“Yes” / “No” is the preferred form because that is what M-Files displays in the UI and what users see in their property cards. Worth noting: the M-Files Admin label “Boolean (yes/no)” is always English even on a localized vault. So you do not need “Ja” / “Nein” mappings on a German vault (at least as of today).

7. Wrap-up

The query model covers the questions that come up in practice. objectType and class define the scope, filters narrow it with a rich set of operators spanning native server conditions and post-filter cases. Date tokens make filters relative without effort.

What is not in this post: the aggregation block. That is the topic of Post 6, which covers the aggregation types, the reducers, and the multi-series seriesProperty feature. Once those are explained, every JSON block in the widget posts will make complete sense.

Want to know more about this Business Dashboard? Contact us and we will be happy to showcase it on M-Files.