ProConcepts DDL - kataya/arcgis-pro-sdk GitHub Wiki

The DDL API is used to create and delete geodatabases and geodatabase schema objects.

Language:      C#
Subject:       Geodatabase DDL
Contributor:   ArcGIS Pro SDK Team <[email protected]>
Organization:  Esri, http://www.esri.com
Date:         10/07/20
ArcGIS Pro:    2.7
Visual Studio: 2017, 2019

In this topic

Introduction
General Usage
- What are Tokens?
Creating Tables and Feature Classes
Deleting Tables and Feature Classes
Creating and Deleting File Geodatabases
Additional Information

Introduction

One of the biggest requests from our user community has been a ative C# solution for geodatabase DDL (data definition language). We have completed the first pieces of this functionality in the Pro 2.7 release. Since only a small subset of our planned DDL operations are supported, we are releasing this as a pre-release.

The following functionality has been enabled:

Creating and deleting tables in file or enterprise geodatabases
Create and deleting feature classes in file or enterprise geodatabases
Creating and deleting file geodatabases

Our intention is to expand these capabilities in ArcGIS Pro 2.8 and subsequent releases. Although we intend to only add to the classes presented here, while in pre-release status we reserve the right to make API changes based on user feedback.

At Pro 2.7, the classes described here can be found in the ArcGIS.Core.Internal.Data.DDL namespace. Because this material in this pre-release, they do not appear in the online API reference.

General Usage

As with most of the geodatabase API, the classes and methods detailed here are intended to be called on the Main CIM Thread (MCT) as described in ProConcepts-Geodatabase.

The DDL routines follow a common pattern. A Description class is used to specify the schema object to be created or deleted. For example, a TableDescription describes a table. One of the properties of a table description is a list of FieldDescription objects to specify the fields.

// Create a FieldDescription for the InspectionDate field
FieldDescription inspectionDateFieldDescription = new FieldDescription("InspectionDate", FieldType.Date)
{
  AliasName = "Inspection Date"
};

Generally, Description objects are either created by hand using a set of properties, or are created using an existing schema object.

Schema objects are created and deleted using a SchemaBuilder object, which is constructed with a Geodatabase. Only file and enterprise geodatabases are supported.

// Create a SchemaBuilder object
SchemaBuilder schemaBuilder = new SchemaBuilder(geodatabase);

DDL operations for creation are enqueued with the schema builder using a set of calls to Create methods.

// Add the creation of the table to our list of DDL tasks
schemaBuilder.Create(tableDescription);

The set of DDL operations is then executed with a call to Build. If the process fails, the SchemaBuilder.ErrorMessages property can be queried to find out what went wrong.

// Execute the DDL
bool success = schemaBuilder.Build();

DDL routines can fail for the same reason that the equivalent geoprocessing tool can do so. For example, if a table has outstanding edits, you cannot delete it.

In terms of failures, the Build operation is not guaranteed to be atomic. For example, consider a build operation that creates two tables. If the second table creation fails, the first table would still be created. It is the responsibility of the caller to check the ErrorMessages property and do any required clean-up in the case of failure. In the example above, if the second table creation fails, the caller may wish to delete the first table in a subsequent call to SchemaBuilder.Build.

The same SchemaBuilder object can be used for multiple sets of DDL operations, each executed by a call to Build.

What are Tokens?

Each Create method returns a Token object. Although not useful in this pre-release, these tokens will be used to specify dependencies between DDL operations. For example, the Create(TableDescription) routine returns a TableToken. A developer could create two tables, getting back two TableToken objects. These table tokens could then be used as input to create a RelationshipClassDescription, which is passed to its own create call. In this way, a single call to SchemaBuilder.Build could create two tables and a relationship class between them.

Creating Tables and Feature Classes

This pre-release version allows the creation of tables and feature classes in file and enterprise geodatabases.

To create a table, the first step is to create a series of FieldDescription objects.

Each of these represents the definition of a field to be created on the new table. You can create a FieldDescription from an existing Field or by individually setting properties. Static helper routines are provided for creating common types of fields. Some examples of creating fields are shown below:

// Create a FieldDescription for the InspectionDate field
FieldDescription inspectionDateFieldDescription = new FieldDescription("InspectionDate", FieldType.Date)
{
  AliasName = "Inspection Date"
};

// This static helper routine creates a FieldDescription for a Domain field (from a pre-existing domain)
FieldDescription inspectionResultsFieldDescription = FieldDescription.CreateDomainField("InspectionResults", new CodedValueDomainDescription(inspectionResultsDomain));
inspectionResultsFieldDescription.AliasName = "Inspection Results";

Note the use of the CodedValueDomainDescription object in the last example above. Although domain creation will be supported in a future release, for now you can only create fields using pre-existing domains.

After creating the desired set of FieldDescription objects, the next step is to create a TableDescription object representing the definition of the table itself.

The TableDescription is passed to SchemaBuilder.Create and then SchemaBuilder.Build is used to actually create the table.

// Assemble a list of all of our field descriptions
List<FieldDescription> fieldDescriptions = new List<FieldDescription>() 
  { globalIDFieldDescription, objectIDFieldDescription, inspectionDateFieldDescription, inspectionResultsFieldDescription, inspectionNotesFieldDescription };

// Create a TableDescription object to describe the table to create
TableDescription tableDescription = new TableDescription("PoleInspection", fieldDescriptions);

// Create a SchemaBuilder object
SchemaBuilder schemaBuilder = new SchemaBuilder(geodatabase);

// Add the creation of PoleInspection to our list of DDL tasks
schemaBuilder.Create(tableDescription);

// Execute the DDL
bool success = schemaBuilder.Build();

Creating a feature class follows much of the same principles as creating a table. One addition is that you must create a ShapeDescription object to represent the defintion of the shape field.

ShapeDescription objects can be created from a set of properties or by using the FeatureClassDefinition of an existing feature class.

// Create a ShapeDescription object
ShapeDescription shapeDescription = new ShapeDescription(GeometryType.Point, spatialReference);

// Alternatively, ShapeDescriptions can be created from another feature class.  In this case, the new feature class will inherit the same shape properties of the existing class
ShapeDescription alternativeShapeDescription = new ShapeDescription(existingFeatureClass.GetDefinition());

The final step is to create a FeatureClassDescription and build the feature class using the same pattern described above.

// Create a FeatureClassDescription object to describe the feature class to create
FeatureClassDescription featureClassDescription = new FeatureClassDescription("Cities", fieldDescriptions, shapeDescription);

// Create a SchemaBuilder object
SchemaBuilder schemaBuilder = new SchemaBuilder(geodatabase);

// Add the creation of the Cities feature class to our list of DDL tasks
schemaBuilder.Create(featureClassDescription);

// Execute the DDL
bool success = schemaBuilder.Build();

Deleting Tables and Feature Classes

This pre-release version also allows the deletion of tables and feature classes in file and enterprise geodatabases. In both cases, a Description object is created and passed to the SchemaBuilder.Delete method. TableDescription and FeatureClassDescription objects can be easily constructed by passing in the defintion of an existing table or feature class.

// Create a TableDescription object
TableDescription tableDescription = new TableDescription(table.GetDefinition());

// Create a SchemaBuilder object
SchemaBuilder schemaBuilder = new SchemaBuilder(geodatabase);

// Add the deletion of the table to our list of DDL tasks
schemaBuilder.Delete(tableDescription);

// Execute the DDL
bool success = schemaBuilder.Build();

Creating and Deleting File Geodatabases

Creating a deleting file geodatabases follow a slightly different pattern than the other DDL operations. Static routines on the SchemaBuilder class called CreateGeodatabase and DeleteGeodatabase are used to create and delete file geodatabases. Both routines take a FileGeodatabaseConnectionPath as an argument.

If a file geodatabase is in use, it cannot be deleted. All geodatabase objects that refer to the file geodatabase, or datasets or rows within it, must be disposed prior to deletion.

Additional Information

A full set of examples showing the use of these DDL routines can be found on the snippets page.

The following object model diagrams describe the classes available in this pre-release.