Reader Directives – All Geodatabase Types

This section describes the directives that are recognized by the Core Geodatabase reader module.

Each directive is prefixed by the current <ReaderKeyword>_ when placed in a mapping file. Unless otherwise specified, the <ReaderKeyword> for the Geodatabase reader is the same as the <ReaderType>.

FEATURE_READ_MODE

This directive provides the ability to read table-level metadata when set to Metadata. In this mode, the reader outputs one feature per feature type. The geodb_type of the feature is geodb_metadata and the entire XML metadata document belonging to the Geodatabase table is found in the attribute geodb_metadata_string.

Where applicable, the following attributes are also supplied:

  • fme_feature_identifier which indicates the name of the object ID field,
  • fme_num_entries (Personal Geodb only) which indicates the number of features in the table,
  • fme_contains_spatial_column which indicates whether the table has a geometry column (or, in Esri ArcGIS terms, whether the table is a feature class)
  • fme_geometry{0} which indicates the types of geometry the feature class contains
  • fme_dimension which indicates whether the feature class is 2D or 3D.

If the table is a feature class, the geometry of the metadata feature returned is a polygon, representing the extents of the feature class, and the coordinate system of the feature class also gets set on the feature.

When reading metadata, the IDs and DEF keywords are used to determine which feature types should have metadata read from them.

When set to Features, the reader outputs features stored within tables.

Required/Optional

Optional

Parameter

<feature_read_mode>

Values

Features (default) | Metadata

Mapping File Syntax

GEODATABASE_SDE_FEATURE_READ_MODE Metadata

Workbench Parameter

Feature Read Mode

WHERE

An SQL-like (determined by the underlying database) WHERE clause that selects only certain records for extraction from the Geodatabase.

The specified WHERE clause is passed to the Geodatabase for processing. The WHERE clause can be almost like an SQL clause (using the syntax supported by the underlying database) except that ORDER BY, GROUP BY, nested queries, and aggregate functions (i.e. MAX, COUNT) cannot be used.

This WHERE clause applies to all tables retrieved. For more specific queries, see the Reader directive DEF.

Required/Optional

Optional

Workbench Parameter

Where Clause

Example:

The WHERE clause specified below instructs the FME to retrieve features from the Geodatabase for the tables that are listed on the <ReaderKeyword>_IDs lines (unless no _IDs lines are specified in which case all tables are examined).

The features retrieved must have for their ObjectID a value greater than 10 and their City attribute must be Vancouver.

GEODATABASE_SDE_WHERE ObjectID > 10 AND \
City =‘Vancouver’

DEF

Required/Optional: Optional

Describes tables. Normally these lines are automatically generated within a mapping file using FME. When reading from an Enterprise Geodatabase, the table names on the DEF lines may be prefixed by the user ID of the person who created the table, followed by a period (for example, <userid>.<tablename>). The only table names that must be prefixed by a user ID are those tables that were not created using your own user ID. However, you may still not be able to access another person’s tables if your user ID doesn't have the correct privileges.

This directive is usually automatically generated while generating a mapping file for a specific Geodatabase, but there is one way it can be customized. An automatically generated DEF might look like this:

GEODATABASE_MDB_DEF IndexGrid \
geodb_type geodb_polyline \
GEODB_OID integer \
OBJECTID integer \
Entity char(254) \
Handle char(254) \
Layer char(254) \
Color integer \
Linetype char(254) \
Elevation double \
Thickness double \
SHAPE_Length double

Note: The returned feature types will match the table names on the DEFs exactly (including the character case). As a result, if the DEF’s table name was IndexGrid (with no owner prefix) then the feature type of the returned features would also be IndexGrid. If the DEF’s table name was sde.IndexGrid then the feature type would be sde.IndexGrid.

Customizing Reader DEF Lines

With already generated and working DEF lines, a WHERE clause can be added just like a normal attribute on a DEF line above, except that instead of the type (such as double), the value will be an SQL WHERE clause. This clause MUST be in double quotation marks ("") and must conform to the same restrictions as the WHERE clause directive listed above. In addition, the clause cannot be continued on to the next line so a continuation character (\) cannot appear in the middle of the clause.

Example

The WHERE clause specified below instructs the FME to retrieve features from the feature class IndexGrid with the constraint that the Color value must be 5. Note that the WHERE clause is case-sensitive, and can appear on any line.

GEODATABASE_MDB_DEF IndexGrid \
geodb_type geodb_polyline \
GEODB_OID integer \
OBJECTID integer \
Entity char(254) \
Layer char(254) \
Color integer \
Linetype char(254) \
Elevation double \
Thickness double \
WHERE "Color = 5" \
SHAPE_Length double

IDs

Required/Optional: Optional

This statement specifies the tables from which features are to be retrieved. There may be multiple GEODATABASE_<SDE|MDB|FILE>_IDs statements within a single FME mapping file, in which case the input set of tables comprises the union of all GEODATABASE_<SDE|MDB|FILE>_IDs statements. The Geodatabase reader module only extracts features from the identified tables. If no GEODATABASE_<SDE|MDB|FILE>_IDs lines appear in the mapping file, then all tables with DEF lines will be used as the input set. If the Personal Geodatabase or File-based Geodatabase reader is being used and there are no DEF lines and no IDs, then all the tables will be read. If the Enterprise Geodatabase reader is being used and there are no DEF lines and no IDs, then no tables will be read. (This behavior is different from reading Personal and File-based Geodatabases.)

The returned feature types will match the IDs exactly (including the character case). As a result, if the IDs was tableOne (with no owner prefix) then the feature type would also be tableOne. If the IDs was sde.tableOne then the feature type would be sde.tableOne.

Parameter: <[table name]+>

Note: The table name must be exactly the same as it appears on the DEF line. For Enterprise Geodatabases, the tables on the DEF line may be prefixed by the user ID and a period (for example, <userid>.). If this is the case, then corresponding tables on the IDs line must also be prefixed by the username and a period.

Workbench Parameter: Feature Types to Read

Enterprise Geodatabase Example:

As shown below, the GEODATABASE_SDE_IDs is a list of table names. In the example, features are read from the table roads, and then from the table streets. Both tables are owned by a user named jacob. Each ID is treated as a separate query to the database. In this example, the assumption is made that the DEF lines for these tables also contain the user ID and a period. If this was not the case, then no tables would be found because the table names on the IDs line would not match up with the table names on the DEF lines, even though they may be referring to the same table.

GEODATABASE_SDE_IDs jacob.roads jacob.streets

Personal and File-based Geodatabase Example:

As shown below, the GEODATABASE_<MDB|FILE>_IDs is a list of table names. In the example, features are read from the table roads, and then from the table streets. Each ID is treated as a separate query to the database. Reading from a File-based Geodatabase would look exactly the same except that the reader directive GEODATABASE_MDB would be replaced with GEODATABASE_FILE.

GEODATABASE_MDB_IDs roads streets

RETRIEVE_ALL_SCHEMAS

This parameter is applicable only when generating a mapping file, generating a workspace, or when retrieving schemas in an FME Objects application.

When set to yes, schemas for all of the tables and feature classes in the database are returned.

When set to no (or missing), and if RETRIEVE_ALL_TABLE_NAMES is similarly set to no (or missing), only schemas requested by the IDs parameter are returned.

Required/Optional

Optional

Values

YES | NO (default)

NO: The reader will return the schemas for the feature types specified in the IDs. If no features are specified in IDs, then FME returns the schema features for all the tables.

If this value is not specified, then it is assumed to be No.

YES: Indicates to the reader to return all the schemas of the tables in the database.

Mapping File Syntax

Not applicable.

FME Objects applications would include RETRIEVE_ALL_SCHEMAS followed by “YES” in the parameters array passed to IFMEUniversalReader::open().

Workbench Parameter

Not applicable

RETRIEVE_ALL_TABLE_NAMES

This parameter is only applicable when generating a mapping file, generating a workspace or when retrieving schemas in an FME Objects application.

When set to yes, and if RETRIEVE_ALL_SCHEMAS is set to no (or missing), names for all of the tables and feature classes in the database are returned. When set to no (or missing), and if RETRIEVE_ALL_SCHEMAS is similarly set to no (or missing), the schemas requested by the IDs directive are returned.

Note: If RETRIEVE_ALL_SCHEMAS is also set to Yes, then RETRIEVE_ALL_SCHEMAS takes precedence.

Required/Optional

Optional

Values

YES | NO (default)

Mapping File Syntax

Not applicable.

FME Objects applications would include RETRIEVE_ALL_TABLE_NAMES followed by “YES” in the parameters array passed to IFMEUniversalReader::open().

Workbench Parameter

Not applicable (used when you browse a Table List)

EXPOSED_ATTRS

This directive allows the selection of format attributes to be explicitly added to the reader feature type.

This is similar to exposing format attributes on a reader feature type once it has been generated; however, it is even more powerful because it enables schema-driven applications other than Workbench to access and leverage these attributes as if they were explicitly on the schema as user attributes.

The result of picking a list of attributes is a comma-separated list of attribute names and types that will be added to the schema features. Currently all reader feature types will receive the same set of additional schema attributes for a given instance of the reader.

Required/Optional

Optional

Mapping File Syntax

Not applicable.

While it is possible for FME Objects applications to invoke this directive, the required format is not documented.

This directive is intended for use in our GUI applications (for example, Workbench) only.

Workbench Parameter

Additional Attributes to Expose

SEARCH_ENVELOPE

Using the minimum and maximum x and y parameters, define a bounding box that will be used to filter the input features. Only features that interact with the bounding box are returned.

If all four coordinates of the search envelope are specified as 0, the search envelope will be disabled.

Mapping File Syntax

<ReaderKeyword>_SEARCH_ENVELOPE <minX> <minY> <maxX> <maxY>

Note: If all four coordinates of the search envelope are specified as zero, the search envelope will be disabled.

Required/Optional

Optional

Workbench Parameter

Minimum X, Minimum Y, Maximum X, Maximum Y

SEARCH_ENVELOPE_COORDINATE_SYSTEM

This directive specifies the coordinate system of the search envelope if it is different than the coordinate system of the data.

The COORDINATE_SYSTEM directive, which specifies the coordinate system associated with the data to be read, must always be set if the SEARCH_ENVELOPE_COORDINATE_SYSTEM directive is set.

If this directive is set, the minimum and maximum points of the search envelope are reprojected from the SEARCH_ENVELOPE_COORDINATE_SYSTEM to the reader COORDINATE_SYSTEM prior to applying the envelope.

Required/Optional

Optional

Mapping File Syntax

<ReaderKeyword>_SEARCH_ENVELOPE_COORDINATE_SYSTEM <coordinate system>

Workbench Parameter

Search Envelope Coordinate System

CLIP_TO_ENVELOPE

This directive specifies whether or not FME should clip features to the envelope specified in the SEARCH_ENVELOPE directive.

Values

YES | NO (default)

Mapping File Syntax

<ReaderKeyword>_CLIP_TO_ENVELOPE [yes | no]

Workbench Parameter

Clip To Envelope

SEARCH_FEATURE

Required/Optional: Optional

The SEARCH_FEATURE clause provides a mechanism for specifying an arbitrarily complex search feature. The SEARCH_FEATURE clause works with the SEARCH_METHOD clause to define the spatial constraint, but cannot be specified at the same time as a SEARCH_ENVELOPE is specified.

Note: It is recommended you use a simplified search feature. If you don’t, the reader will simplify the search feature and this could produce unexpected results.

Parameter: [<xCoord> <yCoord>]+ (A list of the coordinates defining the geometry of the query geometry.)

Workbench Parameter: Search Feature

Example:

The example below defines an equivalent geometry to the GEODATABASE_MDB_SEARCH_ENVELOPE example shown above using the GEODATABASE_<SDE|MDB|FILE>_SEARCH_FEATURE clause.

GEODATABASE_SDE_SEARCH_FEATURE 6190 57239 6190 57549 \
6310 57549 6310 57239 \
6190 57239

SEARCH_ORDER

Required/Optional: Optional

Specifies the order that the underlying search is performed on the Geodatabase. This directive determines whether the spatial component or the attribute component of a query is performed first. The benefit of using this directive is for efficiency. For example, if the attribute component would filter the data more than would the spatial component, then it would be desirable to use the SEARCH_ORDER directive to force the attribute component to be used first. If the directive is not used, then by default the spatial component is used first.

Parameter: <search_order>

Value: SPATIAL_FIRST | ATTRIBUTE_FIRST

Workbench Parameter: Search Order

Example:

GEODATABASE_SDE_SEARCH_ORDER SPATIAL_FIRST

SEARCH_METHOD

Required/Optional: Optional

This directive specifies the type of spatial relationship the queried spatial features must have with either the SEARCH_ENVELOPE or the SEARCH_FEATURE in order to be returned.

Note: Only one of SEARCH_ENVELOPE and SEARCH_FEATURE may be specified at a time.)

Parameter: <search_method>

Values: The values for the search method mostly follow the basic Clementini relationships that are used by Esri. For further information on these relationships, see Exploring ArcObjects Vol. II: Geographic Data Management Chapter 8.

The value of the SEARCH_METHOD can be one of the following:

  • GEODB_INTERSECTS: Features must intersect with the query geometry.
  • GEODB_ENVELOPE_INTERSECTS: The envelopes of the features must intersect with the envelope of the query geometry.
  • GEODB_TOUCHES: Features must touch the query geometry.
  • GEODB_OVERLAPS: The query geometry overlaps the features returned.
  • GEODB_CROSSES: The query geometry crosses the feature returned.
  • GEODB_WITHIN: The query geometry is within the features returned.
  • GEODB_CONTAINS: The query geometry contains the features returned.

Default value: GEODB_INTERSECTS

Workbench Parameter: Search Method

Example:

GEODATABASE_MDB_SEARCH_METHOD GEODB_CONTAINS