4.13 SDO_TOPO_MAP.CREATE_FEATURE
Format (no topology geometry layer hierarchy or lowest level in a hierarchy)
SDO_TOPO_MAP.CREATE_FEATURE( topology IN VARCHAR2, table_name IN VARCHAR2, column_name IN VARCHAR2, geom IN SDO_GEOMETRY ) RETURN SDO_TOPO_GEOMETRY; or SDO_TOPO_MAP.CREATE_FEATURE( topology IN VARCHAR2, table_name IN VARCHAR2, column_name IN VARCHAR2, geom IN SDO_GEOMETRY, snapfeature IN NUMBER ) RETURN SDO_TOPO_GEOMETRY;
Format (parent level in a hierarchy)
SDO_TOPO_MAP.CREATE_FEATURE( topology IN VARCHAR2, table_name IN VARCHAR2, column_name IN VARCHAR2, dml_condition IN VARCHAR2 ) RETURN SDO_TOPO_GEOMETRY;
Description
Creates a feature from Oracle Spatial geometries. (This function is intended to be used for inserting rows into a feature table.)
-
The first two formats (with the
geom
parameter and without thedml_condition
parameter) are for creating a feature in a topology without a topology geometry layer hierarchy or in the lowest level of a topology with a topology geometry layer hierarchy. -
The third format (with the
dml_condition
parameter and without thegeom
parameter) is for creating a feature in a parent level of a topology with a topology geometry layer hierarchy.
Parameters
- topology
-
Topology having the associated specified feature table and feature column.
- table_name
-
Name of the feature table containing the feature column specified in
column_name
. - column_name
-
Name of the feature column (of type SDO_TOPO_GEOMETRY) containing the topology geometries.
- geom
-
Geometry objects.
- snapfeature
-
If set to 1, the specified new feature is snapped to existing edges and nodes in the topology.
- dml_condition
-
For topologies with a topology geometry layer hierarchy (described in Topology Geometry Layer Hierarchy): DML condition for selecting rows from a child layer to be inserted into a parent layer. Specify the condition in a quoted string, but without the word WHERE. For example, to select only rows where the STATE_ABBR column value is
MA
, specify the following:'state_abbr=''MA'''
Usage Notes
This function is used to create features from existing geometries stored in a spatial table. Creating features from existing geometries is one approach to creating topology features; the other approach is to load the topology data into the node, edge, and face information tables. Both approaches are described in Main Steps in Using Topology Data, which contains the following subsections:
-
Using a Topology Built from Spatial Geometries (that is, the approach using the CREATE_FEATURE function)
When you use the first or second format of this function, you must first create and load an updatable TopoMap object. To create a topology feature or an associated topological element, the function internally calls the addPointGeometry
, addLinearGeometry
, or addPolygonGeometry
method of the updatable TopoMap object, depending on the SDO_GTYPE value of the geometry object, and it calls the updateTopology
method of the updatable TopoMap object to write topological elements to the database. If this function is called in an INSERT or UPDATE statement, a feature is created or updated in the feature table. When the function completes, it has the effect of overlaying the geometry onto the topology. (That is, Spatial uses an implicitly created TopoMap object to create a new TopoMap object for each call to this function.)
When you use the third format of this function, you do not need to create an updatable TopoMap object. The function internally collects TG_ID values of features in the child level based on the dml_condition
parameter value, and it assembles an SDO_TGL_OBJECT_ARRAY object to create the SDO_GEOMETRY object.
To ensure that this function works correctly with all geometries, use a loop to call the function for each geometry. Do not use this function in a subquery in an INSERT or UPDATE statement, because doing so may cause inconsistencies in the topology, and you may not receive any error or warning messages about the inconsistencies.
An exception is raised if one or more of the following conditions exist:
-
topology
,table_name
, orcolumn_name
does not exist. -
geom
specifies geometry objects of a type inconsistent with the topology geometry layer type. For example, you cannot use line string geometries to create land parcel features. -
dml_condition
is used with a topology that does not have a topology geometry layer hierarchy. -
The input geometries include any optimized shapes, such as optimized rectangles or circles.
-
A line string or multiline string geometry contains any overlapping line segments.
-
In a multipolygon geometry, an exterior ring overlaps any other exterior ring.
Examples
The following example populates the FEATURE column in the CITY_STREETS, TRAFFIC_SIGNS, and LAND_PARCELS feature tables with all geometries in the GEOMETRY column in the CITY_STREETS_GEOM, TRAFFIC_SIGNS_GEOM, and LAND_PARCELS_GEOM spatial tables, respectively. This example assumes that an updatable TopoMap object has been created and loaded for the CITY_DATA
topology. (The example refers to definitions and data from Topology Built from Spatial Geometries.)
BEGIN FOR street_rec IN (SELECT name, geometry FROM city_streets_geom) LOOP INSERT INTO city_streets VALUES(street_rec.name, SDO_TOPO_MAP.CREATE_FEATURE('CITY_DATA', 'CITY_STREETS', 'FEATURE', street_rec.geometry)); END LOOP; FOR sign_rec IN (SELECT name, geometry FROM traffic_signs_geom) LOOP INSERT INTO traffic_signs VALUES(sign_rec.name, SDO_TOPO_MAP.CREATE_FEATURE('CITY_DATA', 'TRAFFIC_SIGNS', 'FEATURE', sign_rec.geometry)); END LOOP; FOR parcel_rec IN (SELECT name, geometry FROM land_parcels_geom) LOOP INSERT INTO land_parcels VALUES(parcel_rec.name, SDO_TOPO_MAP.CREATE_FEATURE('CITY_DATA', 'LAND_PARCELS', 'FEATURE', parcel_rec.geometry)); END LOOP; END; /
The following example creates a topology that has a topology geometry layer hierarchy with two layers: counties and states. The calls to the CREATE_FEATURE function that create parent layer (state) features include the dml_condition
parameter (for example, 'p_name=''NH'''
).
declare name varchar2(64); cursor c1 is select state_abrv, county from counties order by 1, 2; stateabrv varchar2(2); begin -- Initialize. sdo_topo_map.create_topo_map('cnty', 'm2', 10000, 10000, 10000); sdo_topo_map.load_topo_map('m2', -180, -90, 180, 90, 'true'); -- Insert one county at a time. for cnty_rec in c1 loop stateabrv := cnty_rec.state_abrv; name := cnty_rec.county; insert into cnty_areas select state_abrv || '-' ||county, sdo_topo_map.create_feature('CNTY', 'CNTY_AREAS', 'FEATURE', geom) from counties where state_abrv=stateabrv and county=name; end loop; -- Roll back topology. sdo_topo_map.rollback_topo_map(); sdo_topo_map.drop_topo_map('m2'); -- Roll back inserts. rollback; exception when others then dbms_output.put_line(SQLERRM); sdo_topo_map.rollback_topo_map(); sdo_topo_map.drop_topo_map('m2'); rollback; end; / -- Add parent feature layer. -- -- The following commented out statement can be used to populate the -- child_layer_id parameter in sdo_topo.add_topo_geometry_layer. -- -- select tg_layer_id -- from user_sdo_topo_info -- where TOPOLOGY = 'SC' -- and table_name = 'SC_AREAS'; -- execute sdo_topo.add_topo_geometry_layer('SC','SC_P_AREAS', 'FEATURE', - 'POLYGON', NULL, child_layer_id => 1); -- Create and insert state features (logically) from county features. insert into sc_p_areas (f_name, p_name, feature) values ('NH', 'US', sdo_topo_map.create_feature('SC','SC_P_AREAS','FEATURE','p_name=''NH''')); insert into sc_p_areas (f_name, p_name, feature) values ('CT', 'US', sdo_topo_map.create_feature('SC','SC_P_AREAS','FEATURE','p_name=''CT''')); insert into sc_p_areas (f_name, p_name, feature) values ('ME', 'US', sdo_topo_map.create_feature('SC','SC_P_AREAS','FEATURE','p_name=''ME''')); insert into sc_p_areas (f_name, p_name, feature) values ('MA', 'US', sdo_topo_map.create_feature('SC','SC_P_AREAS','FEATURE','p_name=''MA''')); commit;
Parent topic: SDO_TOPO_MAP Package Subprograms