> For the complete documentation index, see [llms.txt](https://olivers-expression-lab.gitbook.io/filter-expressions-in-fme/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://olivers-expression-lab.gitbook.io/filter-expressions-in-fme/the-formula.md). # The Formula Let's have a look at the filter expression again: ```xml cp:nationalCadastralReference 05430202600946______ ``` Maybe you're wondering about the prefixes * fes: * xmlns: * cp: What's this? Did you ever hear about **XML n**ame**s**paces, aka xmlns? A XML namespace is comparable to * a dictionary or * a telephone book A telephone number is only valid in combination with an area code (which represents a certain city or geographic area). Let's give an example: the telephone number is 501 9985. You may dial it on your phone and maybe someone answers (please don't do it in real!). 501 9985 without a prefix is not specific enough! You'll need an area code and maybe a country code in order to reach someone. If you put the country code "+1" and the area code "604" for greater Vancouver in front of 501 9985 you'll get Safe Softwares phone number: +1 604 501 9985 Let's have a look at another example: take the word "Kindergarten" Does it occur in your dictionary? In german Duden dictionary it does. What does the word mean in your language? W3schools says: "*XML Namespaces provide a method to avoid element name conflicts.*" It means they are used to define unique and precise names. Name conflicts in XML can easily be avoided using a name prefix. Use the following syntax to declare a namespace: **xmlns:prefix="URI"**, e.g. * xmlns:fes="" * xmlns:cp="" Please note that a namespaces points to an **URI** (**U**niform **R**esource **I**dentifier), not an **URL** (**U**niform **R**esource **L**ocator). An URI may be a real URL (internet link) you can open using a browser, but it doesn't have to be! Coming back to filter expressions, we have to define the correct namespace prefixes within our expression in order to get them working. But how to find them out? I'll show you 2 possible ways to get the right namespaces. 1. Examine a feature 2. Examine the Translation Log ## Examine a feature For the first way, we will use another WFS. This time a service providing traffic meters for counting vehicles in North Rhine-Westphalia. The WFS URL is: ```url https://www.wfs.nrw.de/wfs/strassen_nrw?SERVICE=WFS&VERSION=2.0.0 ``` Add a WFS reader to your FME Workbench and configure it the following way:
Select **Zaehlstellen** (counting points) as **\[Feature Types]**. Set **\[Max Features]** to **1** and run the reader (Run Just This). You should see a point feature east of Dortmund. Switch to Translation Log. Scroll upwards and look for **\ GetFeature URL**.
Click on the blue colored URL or copy it to your browser. ``` https://www.wfs.nrw.de/wfs/strassen_nrw?SERVICE=WFS&VERSION=2.0.0&REQUEST=GetFeature&TYPENAMES=ms%3AZaehlstellen&NAMESPACES=xmlns%28ms%2Chttp%3A%2F%2Fmapserver.gis.umn.edu%2Fmapserver%29&OUTPUTFORMAT=application%2Fgml%2Bxml%3B%20version%3D3.2&COUNT=1 ``` Now, you'll see one feature encoded as GML/XML in your browser: ```xml 397181.079930 5708784.375433 397181.079930 5708784.375433 397181.079930 5708784.375433 397181.079930 5708784.375433 397181.079930 5708784.375433 4411120A4411111A 1782.000000000000000 44112109 manuelle Zählstelle (SVZ) 03 Keine Werte (d.h. weder DZ, noch TM, noch MZ-Ergebnisse vorliegend) aktiv (in Betrieb) 20230630190000 ``` We will concentrate on the counting point number "**ZSTNR**": ``` 44112109 ``` As you can see, the attribute comes already together with a namespace prefix: **ms:ZSTNR** Perfect! The only thing we still need is the URI. Finding the URI is also easy! Just look at the xml header: ``` xmlns:ms="http://mapserver.gis.umn.edu/mapserver" ``` Putting the things together, we can modify the filter expression from above the following way: ```xml ms:ZSTNR 52082215 ``` Please use counting point **52082215**. Modify your reader as follows by right clicking on it:
Clear **\[Max Features]** and paste the new filter expression in **\[XML Filter Expression]** editor and run the Workbench. As a result, you'll see a counting point in Bonn, near World Conference Center Bonn (WCCB).
Great! This was easy. ## Examine the Translation Log Coming back to our cadastral parcel service, the things are a little bit more difficult. Add or modify your cadastral parcel WFS reader the following way: | Parameter | Value | | ------------- | ------------------------------------------------------------------- | | WFS URL | | | Feature Types | CadastralParcel | | Max Features | 1 | Run the reader and inspect the Translation Log. Look for **\ GetFeature URL**, which is: ```url https://www.wfs.nrw.de:443/geobasis/wfs_nw_inspire-flurstuecke_alkis?SERVICE=WFS&VERSION=2.0.0&REQUEST=GetFeature&TYPENAMES=cp%3ACadastralParcel&NAMESPACES=xmlns%28cp%2Chttp%3A%2F%2Finspire.ec.europa.eu%2Fschemas%2Fcp%2F4.0%29&OUTPUTFORMAT=application%2Fgml%2Bxml%3B%20version%3D3.2&COUNT=1 ``` and open it in a browser. Save the returned document and open it either in a browser or in a text editor (remember: it is a GML/XML document). It will look like this (some content is turned of "..." for a clearer view): ```xml ... https://registry.gdi-de.org/id/de.nw.inspire.cp.alkis/CadastralParcel_05439400700069______ 35190.00 2017-01-16T15:22:59Z ... CadastralParcel_05439400700069______ https://registry.gdi-de.org/id/de.nw.inspire.cp.alkis 05439400700069______ 315035.325 5579575.262 1974-01-01 ``` We concentrate on the cadastral parcel number attribute: ``` 05439400700069______ ``` As you can see, it comes **without** a namespace prefix, while we're expecting **cp:nationalCadastralReference**. What a bummer! Well then?
We may inspect the header where we will find ```url http://www.wfs.nrw.de/aaa-suite/schema/inspire.ec.europa.eu/schemas/cp/4.0/CadastralParcels.xsd ``` This URL points to a XML schema (\*.xsd). It can also be opened with a browser or text editor.
If you're familiar with XML schemata you may recognize, that the cp:-prefix is passed to **nationalCadastralReference** from **BasicPropertyUnitType** which is a higher-order complex type. **But, never mind!** We will ask our best friend: the Translation Log! First, we will inspect the feature in **Visual Preview** (or **Inspector**)
Next open **\[Columns...]**
On the left side scroll down to the end of the list of available columns and activate **xml\_ns\_uri**.
For a better view, you may move it up near **nationalCadastralReference**. Close the dialog and inspect the new attribute:
``` http://inspire.ec.europa.eu/schemas/cp/4.0 ``` Keep this in mind and switch to Translation Log. Scroll up until you see "**Using prefix ...**" and look for the URI in question.
``` Using prefix 'cp' for uri 'http://inspire.ec.europa.eu/schemas/cp/4.0' ``` Surprise: the correspondig prefix is **cp**! How cool is this!? To complete the formula, we have to discuss **versions**. ## Choosing the right version While treating GetCapabilities I mentioned, that you should use version 2.0.0 if your WFS supports this version. Why? Because there are some differences between * version 1.0.0, 1.1.0 * version 2.0 While we used **\** to query version 2.0 WFS, \ we have to use **\** for version 1.x | Version | Element | Schema | | ------- | ------------------ | -------------------------------------------------- | | 1.0.0 | ogc:PropertyName | \[FMEdir]\xml\schemas\filter\\**1.0.0**\filter.xsd | | 1.1.0 | ogc:PropertyName | \[FMEdir]\xml\schemas\filter\\**1.1.0**\filter.xsd | | 2.0.0 | fes:ValueReference | \[FMEdir]\xml\schemas\filter\\**2.0.0**\filter.xsd | You may have a look at the corresponding schema called filter.xsd. It can be found in FMEs installation directory (FMEdir) on your local hard drive. Another little but tricky difference concerns the defintion of wildcards when using **PropertyIsLike**: | Version | Expression | Expression | Expression | | ------- | ---------- | ---------- | ------------------------------------------ | | 1.0.0 | wildCard | singleChar | **escape** | | 1.1.0 | wildCard | singleChar | escapeChar | | 2.0.0 | wildCard | singleChar | escapeChar | We will discuss the usage of **PropertyIsLike** later on. To summarize let's have a look at our traffic meter WFS from above: | Parameter | Value | | -------------- | ------------------------------------------ | | WFS URL | | | Version | **1.0.0** and **2.0.0** | | Features Types | **Zaehlstellen** (*counting points*) | | Max Features | leave blank | If you want to query the service in **version 1.0.0/1.1.0** the filter expression should look like this: ``` ms:ZSTNR 52082215 ``` and in **version 2.0.0** like this: ``` ms:ZSTNR 52082215 ``` **Caution**: You may notice that \ works with version 1.0.0/1.1.0 as well! This is usually the case, if the WFS supports both, 1.x and 2.0. But if you stumble on a version 1.x only WFS, please keep this in mind! Ok, now we know how to collect the information we need to write perfect filter expressions. Let's put the theory into practice! ## Good to know #3 Sometimes it is a good idea to check if your **XML** Filter Expression **is well formed**, i.e. if the syntax is correct. Especially if you copy & paste some code from the internet it may happen that quotation marks or something else gets lost. There are tons of XML validation tools in the internet. My personal favorite is ```url https://jsonformatter.org/xml-validator ```
Q: What's going wrong here? A: The closing quotation mark is missing!