Saturday, 23 February 2013

MapGuide tidbits: Data filters

For this post, we're going to cover briefly about Data Filters

Filters are what can be passed to FDO feature queries for returning/excluding certain features

For example, filters can be used to restrict what gets rendered for a particular layer


They are also used to define what features fall under a certain theme rule



Filters also form the backbone of search commands in the AJAX viewer (and for those wondering, $USER_VARIABLE is the special search command placeholder that gets replaced with whatever the user enters in the search command prompt)


So that's all and good. I'm sure most of you are already aware of what filters are supposed to do. But what some of you are most likely confused by is the actual syntax of these filters.

If you're coming from a MapGuide 6.5 or older background, you are probably assuming these filters are just SQL where clauses. This is not the case with FDO.

FDO is a data abstraction layer after all, meaning we also need a "one size fits all" abstract filtering grammar that can be easily processed and handled in a provider-specific manner (eg. translation to equivalent SQL where clauses)

The BNF of FDO filters can be found in the FDO Developer's Guide. Here's the relevant link for convenience. If this BNF stuff confuses you, the upshot of all this is that for the most part FDO filters are similar, if not identical to SQL where clauses but there are some cases where certain conditions may look a bit un-intuitive.

For example, assuming you know your SQL you might think a NULL condition may look like this:

COLUMN_NAME IS NULL

When in actuality, such a condition does not work as a FDO filter due to incompatibilities with the FDO filter grammar. The equivalent condition in FDO is actually:

COLUMN_NAME NULL

Similarly, you may think that the negated form of the above condition would look like this:

COLUMN_NAME IS NOT NULL

When in actuality, the FDO equivalent is actually:

NOT COLUMN_NAME NULL

If you look at the BNF of the FDO filter grammar, you can see why NULL conditions are structured this way. But as I've already mentioned, such cases are rare and for the most part FDO filters are syntactically similar to most SQL where clauses.

The second thing to note about filters is that some functions may not work for some FDO providers. Not all providers are created equal in terms of features and capabilities and the same differences apply for filters. Now you can safely assume that the key operators will be supported by all FDO providers (A FDO provider would be pretty useless if you can't do a basic A = B comparison filter), but in terms of filter functions, support can vary from provider to provider.

The FDO provider's capabilities (which can be accessed via MgFeatureService.GetCapabilities() ), describe what functions are supported. The good news about this is if you are only using Maestro to construct such filters (for layers, search commands, etc), these differences are insulated from you because Maestro uses the provider's capabilities to present only to you a list of the supported functions in its Expression Editor UI.

Thus assuming you are constructing a syntactically valid FDO filter, it is impossible to actually construct a filter in Maestro that is not supported by the underlying provider. For FDO Toolbox, we use the same technique for its Expression Editor UI as well.

Hope this post sheds more light about filtering.

1 comment:

Alex Jacobson said...

Jackie - is there a way to set a data filter on a layer in fusion at runtime? For example, I would like a fusion app to only display features with attribute ProjectID = 10, which would be passed to the application by a url parameter.