Extract Data By Feature (Topographic Production)

Summary

Extracts features from multiple input feature classes into a target database.

This tool can extract all features, only the schema, or features that match filter criteria. Features can be filtered based on a polygon feature. The Target Geodatabase parameter can be a database containing input schema, or it can be an empty database in which the tool will create a schema that matches the input dataset.

Usage

• The Input Datasets parameter supports points, polylines, polygons, and annotation features.

• If the input features include a topology, features are extracted from all the layers that participate in that topology. This may be in addition to the layers specified in the Input Datasets parameter.

• The extracted data will use the same names as the data provided for the Input Datasets parameter.

• All Input Datasets parameter values must originate from the same workspace. For example, if the extracted data originates from a feature dataset, the tool will create a feature dataset of the same name in the target geodatabase.

• The target geodatabase must exist before you run this tool.

• The Re-use Schema parameter is enabled for file geodatabases only.

• The Filter Feature Layer parameter requires that one feature is selected.

• The selected feature in the Filter Feature Layer parameter must be a polygon. If it is not, the tool will return an error.

• If the target geodatabase is a Microsoft SQL Server Express database and some of the input datasets are open in ArcGIS Pro, the extraction may fail due to schema locks.

• If a replica with the same name exists in either the source or target geodatabase, the operation will fail and the tool will return an error.

• If you are creating a checkout replica, the input datasets must be registered as versioned.

• Web feature services are not supported for extraction at this time.

• Enterprise databases are not supported as a Target Geodatabase parameter value at this time.

• Related data is extracted by default. To avoid extracting related data, you must specify each relationship class that defines the related objects you want to exclude using the Excluded Relationship Classes parameter.

• Related data is extracted in a forward direction, from origin to destination.

• The Expression parameter value will be applied to all Input Datasets parameter values and the fields used in the SQL expression must exist in all tables. If they don't, the tool will fail and report the name of the tables that don't satisfy the expression. This also applies to feature layers with invalid definition queries.

• The SQL query build drop-down options in the Expression parameter will contain a list of the fields that are shared by all of the Input Datasets parameter values.

• When the Checkout replica parameter is checked, the Filter Spatial Relation parameter only supports the Intersects and Contains options. The Filter Spatial Relation parameter's Clip option is only supported when the Checkout replica parameter is unchecked.

Parameters

Dialog

Label	Explanation	Data Type
Input Datasets	A value table of rows that contain a dataset to extract and a filter option for that dataset. Specifying a filter option allows you to control how rows are replicated in each dataset. The following are the filter options: Dataset—The schema of the dataset will be extracted to the child workspace. Rows Option—Specifies whether all rows, only the schema, or features that match filter criteria will be extracted. All Rows—All rows of the dataset will be extracted to the child workspace. Schema Only—Only the schema of the dataset will be extracted to the child workspace. Use Filters—If a feature layer is specified for the Filter Feature Layer parameter, features that either intersect or are contained by features in the Filter Feature Layer parameter value will be extracted.	Value Table
Target Geodatabase	The workspace into which data will be extracted.	Workspace; GeoDataServer
Re-use Schema (Optional)	Specifies whether the schema of the data that will be extracted will be reused. This reduces the amount of time required to extract the data. This parameter is only supported for file geodatabases. Checked—The schema will be reused. Unchecked—The schema will not be reused. This is the default.	Boolean
Filter Feature Layer (Optional)	A feature layer with one selected feature that will be used to limit the extent of the extracted data.	Layer
Filter Spatial Relation (Optional)	Specifies the spatial relationship between the Filter Feature Layer and Input Datasets parameter values and how that relationship will be filtered. The spatial relationship is applied to data in an extent defined by the area of interest (AOI) specified in the Filter Feature Layer parameter. Intersects—Features in the Input Datasets parameter value that intersect features in the Filter Feature Layer parameter value will be extracted. Contains—Features in the Input Datasets parameter value that are contained by the selected feature in the Filter Feature Layer parameter value will be extracted. Clip—Features in the Input Datasets parameter value that intersect features in the Filter Feature Layer parameter value will be extracted, the features will be split at the AOI boundary, and only the features within the AOI will be kept. Intersects—Features in the in_datasets parameter value that intersect features in the filter_feature parameter value will be extracted. Contains—Features in the in_datasets parameter value that are contained by the selected feature in the filter_feature parameter value will be extracted. Clip—Features in the in_datasets parameter value that intersect features in the filter_feature parameter value will be extracted, the features will be split at the AOI boundary, and only the features within the AOI will be kept.	String
Checkout replica (Optional)	Specifies whether the replica will be checked out, replicated, edited, and checked back in one time. Checked—The replica will be checked out. Unchecked—The replica will not be checked out. This is the default.	Boolean
Replica Name (Optional)	The name of the replica that will be checked out.	String
Expand Feature Classes and Tables (Optional)	Specifies whether expanded feature classes and tables—such as those in networks, topologies, or relationship classes—will be added. Use defaults—The expanded feature classes and tables related to the feature classes and tables in the replica will be added. The default for feature classes is to replicate all features intersecting the spatial filter. If no spatial filter has been provided, all features are included. The default for tables is to replicate only the schema. Add with schema only—Only the schema for the expanded feature classes and tables will be added. All rows—All rows for expanded feature classes and tables will be added. Do not add—No expanded feature classes and tables will be added. This is the default.	String
Replicate Related Data (Optional)	Specifies whether rows related to existing rows in the replica will be replicated. For example, consider a feature (f1) inside the replication filter and a related feature (f2) from another class outside the filter. Feature f2 will be included in the replica if you choose to replicate related data. Checked—Related data will be replicated. Unchecked—Related data will not be replicated. This is the default.	Boolean
Excluded Relationship Classes (Optional)	The relationship classes with the relationships to exclude from extraction. The relationship classes will still be included if both datasets that participate are present, but the related objects are not extracted.	Relationship Class
Expression (Optional)	An SQL expression that is used to further refine results from the AOI extraction.	SQL Expression

Derived Output

Label	Explanation	Data Type
Updated Target Geodatabase	The updated target geodatabase.	Workspace; GeoDataServer

Python

arcpy.topographic.ExtractDataByFeature(in_datasets, target_gdb, {reuse_schema}, {filter_feature}, {filter_type}, {checkout_replica}, {replica_name}, {expand_feature_classes_and_tables}, {get_related_data}, {excluded_rel_classes}, {where_clause})

Name	Explanation	Data Type
in_datasets [[Dataset, Rows Option],...]	A value table of rows that contain a dataset to extract and a filter option for that dataset. Specifying a filter option allows you to control how rows are replicated in each dataset. The following are the filter options: Dataset—The schema of the dataset will be extracted to the child workspace. Rows option—Specifies whether all rows, only the schema, or features that match filter criteria will be extracted. ALL_ROWS—All rows of the dataset will be extracted to the child workspace. SCHEMA_ONLY—Only the schema of the dataset will be extracted to the child workspace. USE_FILTERS—If a feature layer is specified for the filter_feature parameter, features that either intersect or are contained by features in the filter_feature parameter value will be extracted.	Value Table
target_gdb	The workspace into which data will be extracted.	Workspace; GeoDataServer
reuse_schema (Optional)	Specifies whether the schema of the data that will be extracted will be reused. This reduces the amount of time required to extract the data. This parameter is only supported for file geodatabases. REUSE—The schema will be reused. DO_NOT_REUSE—The schema will not be reused. This is the default.	Boolean
filter_feature (Optional)	A feature layer with one selected feature that will be used to limit the extent of the extracted data.	Layer
filter_type (Optional)	Specifies the spatial relationship between the filter_feature and in_datasets parameter values and how that relationship will be filtered. The spatial relationship is applied to data in an extent defined by the area of interest (AOI) specified in the filter_feature parameter. INTERSECTS—Features in the in_datasets parameter value that intersect features in the filter_feature parameter value will be extracted. CONTAINS—Features in the in_datasets parameter value that are contained by the selected feature in the filter_feature parameter value will be extracted. CLIP—Features in the in_datasets parameter value that intersect features in the filter_feature parameter value will be extracted, the features will be split at the AOI boundary, and only the features within the AOI will be kept.	String
checkout_replica (Optional)	Specifies whether the replica will be checked out, replicated, edited, and checked back in one time. CHECKOUT_REPLICA—The replica will be checked out. DO_NOT_CHECKOUT_REPLICA—The replica will not be checked out. This is the default.	Boolean
replica_name (Optional)	The name of the replica that will be checked out.	String
expand_feature_classes_and_tables (Optional)	Specifies whether expanded feature classes and tables—such as those in networks, topologies, or relationship classes—will be added. USE_DEFAULTS—The expanded feature classes and tables related to the feature classes and tables in the replica will be added. The default for feature classes is to replicate all features intersecting the spatial filter. If no spatial filter has been provided, all features are included. The default for tables is to replicate only the schema. ADD_WITH_SCHEMA_ONLY—Only the schema for the expanded feature classes and tables will be added. ALL_ROWS—All rows for expanded feature classes and tables will be added. DO_NOT_ADD—No expanded feature classes and tables will be added. This is the default.	String
get_related_data (Optional)	Specifies whether rows related to existing rows in the replica will be replicated. For example, consider a feature (f1) inside the replication filter and a related feature (f2) from another class outside the filter. Feature f2 will be included in the replica if you choose to get related data. DO_NOT_GET_RELATED—Related data will not be replicated. This is the default. GET_RELATED—Related data will be replicated.	Boolean
excluded_rel_classes [excluded_rel_classes,...] (Optional)	The relationship classes with the relationships to exclude from extraction. The relationship classes will still be included if both datasets that participate are present, but the related objects are not extracted.	Relationship Class
where_clause (Optional)	An SQL expression that is used to further refine results from the AOI extraction.	SQL Expression

Derived Output

Name	Explanation	Data Type
updated_target_gdb	The updated target geodatabase.	Workspace; GeoDataServer

Code sample

ExtractDataByFeature example (stand-alone script)

The following stand-alone script demonstrates how to use the ExtractDataByFeature function to extract features from an input feature class into a target file geodatabase.

# Name: ExtractDataByFeature_sample.py
# Description: Extracts features from an input feature class into a target file geodatabase.

# Import System Modules
import arcpy

# Check Out Extensions
arcpy.CheckOutExtension('Foundation')

# Making AOI Feature Layer
Index = r'C:\Data\ReferenceData\MapIndex.gdb\MapIndex\TM50_Index'
arcpy.management.MakeFeatureLayer(Index, "TM50_Index")

# Selecting a single AOI from the AOI feature layer
selection_string = "NRN = 'V795X16573'"
arcpy.management.SelectLayerByAttribute("TM50_Index", "NEW_SELECTION", selection_string)

# Setting Local Variables
in_datasets = r'C:\Data\TDS_7.gdb\TDS\StructurePnt'
target_gdb = r'C:\Data\ExtractTest.gdb'
reuse_schema = "DO_NOT_REUSE"
filter_feature = "TM50_Index"
filter_type = "CONTAINS"
checkout_replica = "DO_NOT_CHECKOUT_REPLICA"
replica_name = ''
expand_feature_classes_and_tables = 'DO_NOT_ADD'
get_related_data = 'DO_NOT_GET_RELATED'
excluded_rel_classes = None
where_clause = ''

# Calling the Extract Data By Feature tool to extract Structure Point features to a target file geodatabase
arcpy.topographic.ExtractDataByFeature(in_datasets, target_gdb, reuse_schema, filter_feature, filter_type, checkout_replica, replica_name, expand_feature_classes_and_tables, get_related_data, excluded_rel_classes, where_clause)

# Getting all messages, warnings, and errors from the tool run and printing the results back to the user
messages = arcpy.GetMessages(0)
warnings = arcpy.GetMessages(1)
errors = arcpy.GetMessages(2)
arcpy.AddMessage('Tool Messages: {}\nTool Warnings: {}\nTool Errors{}\n'.format(messages, warnings, errors))

# Check In Extensions
arcpy.CheckInExtension('Foundation')

Environments

This tool does not use any geoprocessing environments.

Licensing information

• Basic: No
• Standard: Requires Production Mapping
• Advanced: Requires Production Mapping