SDO_TOPO_MAP.CREATE

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 the dml_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 the geom 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 Topology Data
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, or column_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;