XQuery Functions

This function retrieves the value of an attribute from the current feature.  It has two declarations:

fme:get-attribute( <attribute name> )

fme:get-attribute( <attribute name>, <default value> )

If a second parameter is provided, and the feature does not have a value for the given attribute name, the function will simply return the value of the second parameter.  The second parameter may be any type of XQuery value: string, number, XML node, nested function call, etc.

If a second parameter is not provided, and the feature has no value for the given attribute, the function will simply return an empty sequence. 

String values returned by this function will be converted to be serializable in the context in which they are used. In particular, if the value is being inserted into an XML document, any XML syntax will be escaped. For example, < characters will become &lt; and > will become &gt;. The fme:get-xml-attribute function may be used to return XML nodes. Similarly, if the value is being inserted into a JSON document, the value will be enclosed in quotes, and reserved characters will be escaped. The fme:get-json-attribute may be used to return JSON objects or arrays.

Example:

Consider a feature with the following attributes:

The fme:get-attribute function returns the following results:

This function retrieves the contents of a list attribute from the current feature.  It also has two declarations:

fme:get-list-attribute( <attribute name> )

fme:get-list-attribute( <attribute name>, < delimiter > )

If no delimiter parameter is provided, the function will return the list attribute as a sequence of individual items.  If a delimiter parameter is provided, the function will serialize the contents of the list attribute into a single string, using the value of the delimiter parameter as a delimiter.

As with the fme:get-attribute function, all string values returned by this function will be converted to be valid XML or JSON strings, depending on the context of the function call. The fme:get-xml-list-attribute function may be used to retrieve a list of XML nodes, and the fme:get-json-list-attribute function may be used to retrieve a list of JSON objects or arrays.

Example:

Consider a feature with the following attributes:

The fme:get-list-attribute function returns the following results:

This function retrieves attributes containing XML nodes.  It has only one declaration:

fme:get-xml-attribute( <attribute name> )

If the given attribute contains XML text, this function will parse the text and return an XML node.  If the attribute does not contain XML text, the function will return an empty sequence.

Example:

Consider a feature with the following attributes:

The fme:get-xml-attribute function returns the following results:

This function is similar to the fme:get-xml-attribute function, but retrieves list attributes.  It has two declarations:

fme:get-xml-list-attribute( <attribute name> )

fme:get-xml-list-attribute( <attribute name>, <delimiter> )

The function attempts to parse each value in the list attribute into an XML node.  Values which are not valid XML will be skipped.  If the delimiter parameter is provided, it will be copied into the return sequence between each parsed XML value.

Example:

Consider a feature with the following attributes:

The fme:get-xml-list-attribute function may be used as shown below:

This function retrieves attributes containing JSON objects or arrays. It has only one declaration:

fme:get-json-attribute( <attribute name> )

If the given attribute contains JSON values, this function will parse the text and return a JSON object or array. If the attribute does not contain JSON text, the function will return an empty sequence.

Example:

Consider a feature with the following attributes:

The fme:get-json-attribute function returns the following results:

This function is similar to the fme:get-json-attribute function, but retrieves list attributes. It has only one declaration:

fme:get-json-list-attribute( <attribute name> )

The function attempts to parse each value in the list attribute into a JSON object or array. Values which are not valid JSON will be skipped.

Example:

Consider a feature with the following attributes:

The fme:get-json-attribute function may be used as shown below:

This function allows access to a feature’s coordinate system. If a feature has a coordinate system, the function will return the name of the coordinate system. If the feature does not have a coordinate system, no value will be returned.

This function is very simple.  It returns a boolean (true/false) value indicating whether or not an attribute exists on the current feature.  It has one declaration:

fme:has-attribute( <attribute name> )

Example:

Consider a feature which has only one attribute: ‘name’.  The fme:has-attribute function returns the following results:

This function returns a boolean (true/false) value indicating whether or not all of the attributes listed as parameters exist on the current feature. It has one declaration:

fme:has-all-attributes( <attribute names> )

Example:

Consider a feature which has a ‘name’ and an ‘id’ attribute.  The fme:has-all-attributes function returns the following results:

This function returns a boolean (true/false) value indicating whether or not any of the attributes listed as parameters exist on the current feature. It has one declaration:

fme:has-any-attributes( <attribute names> )

Example:

Consider a feature which has a ‘name’ and an ‘id’ attribute.  The fme:has-any-attributes function returns the following results:

This function sets the value of a feature attribute.  It has two declarations:

fme:set-attribute( <attribute name>, <sequence of values> )

fme:set-attribute( <attribute name>, <sequence of values>, <delimiter> )

The feature attribute will be set to the serialized value of the sequence of values. If the sequence contains more than one value, the values will be concatenated into a delimited string, and the attribute will be set to this concatenated value. The default delimiter is a comma, but the third parameter may be used to provide a different delimiter.

This function does not return a value.

Example

The following XML document is the context item for the examples in this section.

<country>

<name>MONTSERRAT</name>

<area>583.776</area>

<cities>

<city>Plymouth</city>

<city>Brades</city>

</cities>

</country>

After running the following query:

fme:set-attribute( "name_xml", /country/name ),

fme:set-attribute( "area", /country/area/text() ),

fme:set-attribute( "city_list", /country/cities/city/text() ),

fme:set-attribute( "city_list2", /country/cities/city/text(), "|" )

The feature has the following attributes:

This function is very similar to the fme:append-attribute function, but it appends to the value of a feature attribute, rather than replacing the attribute value. It has two declarations:

fme:append-attribute( <attribute name>, <sequence of values> )

fme:append-attribute( <attribute name>, <sequence of values>, <delimiter> )

The serialized value of the sequence of values will be appended to the feature attribute. If the sequence contains more than one value, the values will be concatenated into a delimited string before being appended to the attribute. The default delimiter is a comma, but the third parameter may be used to provide a different delimiter.

This function does not return a value.

This function sets the value of a feature list attribute.  It has only one declaration:

fme:set-list-attribute( <attribute name>, <sequence of values> )

The function serializes each value in the sequence into an element in the list attribute.

This function does not return a value.

Example:

The following XML document is the context item for the examples in this section.

<countries>

<country>

<name>Montserrat</name>

<capital>Plymouth</capital>

</country>

<country>

<name>Christmas Island</name>

<capital>The Settlement</capital>

</country>

<country>

<name>Aruba</name>

<capital>Oranjestad</capital>

</country>

</countries>

After running the following query:

fme:set-list-attribute( "names", /countries/country/name/text() ),

fme:set-list-attribute( "capitals", /countries/country/capital )

The feature has the following attributes:

This function is very similar to the fme:set-list-attribute function, but it appends to the list attribute, rather than overwriting existing values. It has only one declaration:

fme:append-list-attribute( <attribute name>, <sequence of values> )

The function serializes each value in the sequence into an element in the list attribute. Existing list values will be preserved, with the new values appended to the end of the list.

This function does not return a value.

This function will evaluate a template, or set of templates, on features which enter the transformer through the corresponding input ports. The function will return the value of the sub-templates that get processed. This function has two declarations:

fme:process-features( <template names> )

fme:process-features( <template names>, <attributes to filter>, <filter values> )

In both cases, the first parameter is a template name, or list of template names. If no additional parameters are given, the function will execute the listed templates on all features which entered the transformer through the input ports which correspond to those templates. The features will be processed in the order they arrived at the transformer.

The second and third parameters can be used to filter the features which are to be processed. The second parameter should contain an attribute name, or a list of attribute names. The third parameter should contain an attribute value, or a list of values. These parameters should always have the same number of items listed. When the function is called, it will only execute the listed sub-templates on those features which match the following criteria:

• The feature entered the transformer through one of the input ports corresponding to one of the templates listed in the first parameter.
• For each of the attributes listed in the second parameter, the feature’s attribute value matches the corresponding value in the third parameter.

Example:

The following function call will execute the HOUSE sub-template on all features that entered the transformer through the HOUSE input port.

fme:process-features( "HOUSE" )

The following function call will execute the HOUSE sub-template on all features that entered the transformer through the HOUSE input port, and the BUSINESS sub-template on all features which entered through the BUSINESS input port. These features will be processed in the order they arrived at the transformer.

fme:process-features( ("HOUSE", "BUSINESS" ) )

The following function call will execute the HOUSE sub-template on all features that entered the transformer though the HOUSE input port, and whose num_floors attribute is equal to 3.

fme:process-features( "HOUSE", "num_floors", 3 )

The following function call will execute the HOUSE sub-template on all features that entered the transformer through the HOUSE input port, and whose village_id attribute is equal to the id attribute of the feature currently being processed.

fme:process-features( "HOUSE", "village_id", fme:get-attribute( "id" ) )

The following function call will execute the HOUSE sub-template on all features that entered the transformer through the HOUSE input port, and whose num_floors attribute is equal to 3, and whose village_id attribute is equal to the id attribute of the feature currently being processed.

fme:process-features( "HOUSE", ( "num_floors", "village_id" ), ( 3, fme:get-attribute("id") ) )

This function will evaluate a template, or set of templates. Unlike the fme:process-features function, it will evaluate the template on the same feature as the template that contains the function call is being evaluated on. The function has only one declaration:

fme:process-template( <template names> )

The only parameter to this function is a template name, or a list of template names. If more than one name is provided, the templates will be evaluated in the order they are listed.

Example:

The following function call will execute the OWNER template.

fme:process-template( "OWNER" )

The following function call will execute the OWNER and ADDRESS templates.

fme:process-template( ( "OWNER", "ADDRESS" ) )

This function returns the dimension of the geometry currently being processed, as an integer value.

This function returns the name of the geometry currently being processed. If the geometry does not have a name, this function will not return a value.

This function is almost identical to the fme:get-attribute function. It returns the value of a trait on the geometry currently being processed. It has two declarations:

geom:get-trait( <trait name> )

geom:get-trait( <trait name>, <default value> )

If a second parameter is provided, and the geometry does not have a value for the given trait, the function will simply return the value of the second parameter. The second parameter may be any type of XQuery value: string, number, XML node, nested function call, etc.

If a second parameter is not provided, and the geometry has no value for the given trait, the function will not return a value.

These functions return the x/y/z values of a point geometry. They will not return a value if they are executed on a non-point geometry.

Examples:

{

"x" : geom:get-x-coord(),

"y" : geom:get-y-coord(),

"z" : geom:get-z-coord()

}

<point x="geom:get-x-coord()" y="geom:get-y-coord()" z="geom:get-z-coord()" />

These functions return x/y/z values of the start point of linear geometries, such as lines, arcs and paths. If the geometry is a point, these functions will return the x/y/z values of the point geometry. These functions will not return a value for any other type of geometry.

These functions return x/y/z values of the end point of linear geometries, such as lines, arcs and paths. If the geometry is a point, these functions will return the x/y/z values of the point geometry. These functions will not return a value for any other type of geometry.

This function returns a string containing the point values of all points in the geometry being processed. For curved geometries, such as ellipses and arcs, the points in the stroked version will be used. This function has three declarations:

geom:get-points()

geom:get-points( <axis-order> )

geom:get-points( <axis-order>, <axis-separator>, <point-separator> )

The axis order parameter is a string, indicating which order the x, y and z coordinates should appear in the string. If the parameter is not given, the order “xyz” is used. The second parameter indicates the delimiter which is to be used between the x, y, and z values in a point, while the third parameter indicates the delimiter which is to be used between each point. The default axis delimiter is a comma, and the default point delimiter is a space.

Example:

geom:get-points( "xy" )

geom:get-points( "yxz" )

geom:get-points( "yx", "/", " " )

geom:get-points( "xyz", " ", "," )

The last example reverses the default axis and point separators, using a space between the axes and a comma between each point.

This function returns information about arc geometries. If the current geometry is not an arc, the function will not return a value. The function has the following declaration:

geom:get-arc-data( <data names> )

The function expects to be passed a list of strings naming the data which it is to return. The function will return the values as a sequence, in the order they are listed in the function call. Valid names are:

Example:

geom:get-arc-data( "sweep-angle" )

geom:get-arc-data( "center-x", "center-y", "center-z" )

This function returns data about ellipse geometries. If the current geometry is not an ellipse, the function will not return a value. The function has the following declaration:

geom:get-ellipse-data( <data names> )

The function expects to be passed a list of strings naming the data which it is to return. The function will return the values as a sequence, in the order they are listed in the function call. Valid names are:

Example:

geom:get-ellipse-data( "primary-radius", "secondary-radius" )

geom:get-ellipse-data( "rotation" )

This function returns information about text geometries. If the current geometry is not a text geometry, the function will not return a value. The function has the following declaration:

geom:get-text-data( <data names> )

The function expects to be passed a list of strings naming the data which it is to return. The function will return the values as a sequence, in the order they are listed in the function call. Valid names are:

Example:

geom:get-text-data( "rotation" )

geom:get-text-data( "size", "string" )

This function will evaluate a sub-template, based on the type of the geometry currently being processed. This allows a different sub-template to be run for each geometry type. This function has the following declaration:

geom:process-geometry( <conf/> )

As described above, the conf element parameter, or the geometry_template trait will indicate which template to run for each geometry type.

Example:

geom:process-geometry( <conf line="ROAD" point="POI" polygon="PARCEL" /> )

If the geometry currently being processed is a collection (an aggregate or multi-geometry), this function will evaluate a sub-template for each part of the collection. The individual geometries will be processed in the order they appear in the collection, and a sub-template will be chosen based on the type of the geometry. This function may be used to evaluate a template recursively, for example if an aggregate geometry contains another aggregate geometry. As with the other functions in this section, this function takes a conf element as a parameter, which indicates which templates to run for different geometry types.

This function can also be used to evaluate sub-templates on the parts of geometries which are not typically thought of as collections. For example, if the geometry being processed is a path, this function may be used to evaluate a sub-template on each segment of the path. Similarly, if the current geometry is a donut, this function may be used to evaluate a sub-template on each inner boundary of the donut.

This function does not return anything if the geometry being processed is not a collection, path or donut geometry.

Example:

geom:process-parts( <conf area="PARCEL" curve="ROAD" /> )

This function evaluates a sub-template on all points which make up the geometry currently being processed. For example, if the current geometry is a line, the function will evaluate a sub-template on each vertex in the line. If the current geometry is a polygon, the function will evaluate a sub-template on each vertex in the polygon boundary. Arcs and ellipses will be stroked, and a sub-template will be evaluated on each point in the stroked line or polygon. This function has one declaration; unlike the other functions in this section, it does not take a conf element, but takes a single string parameter instead.

geom:process-points( <sub-template name> )

Example:

geom:process-points( "WAYPOINT" )

geom:process-boundary

If the geometry being processed is an area, this function can be used to evaluate a sub-template on the boundary of the area. This function only applies to polygon, donut and ellipse geometries. It has the following declaration.

geom:process-boundary( <conf line="" arc="" path="" /> )

Since the boundary of an area will always be a line, arc or path, these are the only conf attributes which are used by the function, along with the more generic ‘curve’ and ‘all’ attributes. The geom:process-parts function may be used to evaluate a sub-template for each inner boundary of a donut.