Objects Disaggregate statement - MapBasic - 2023

Purpose

Breaks an object into its component parts. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Objects Disaggregate [ Into Table name ]
	[ All | Collection ]
	[ Data column_name = expression [ , column_name = expression ... ]
	[ DropIndex ( Auto | On | Off ) ]

name is a string representing the name of a table to store the disaggregated objects.

column_name is a string representing the name of a column in the table being modified.

expression is an expression used to determine what is placed into the column_name columns.

Description

If an object contains multiple entities, then a new object is created in the output table for each entity.

By default, any multi-part object will be divided into its atomic parts. A Region object will be broken down into some number of region objects, depending on the All flag. If the All flag is present, then the Region will produce a series of single polygon Region objects, one object for each polygon contained in the original object. Holes (interior boundaries) will produce solid single polygon Region objects. If the All flag is not present, then Holes will be retained in the output objects. For example, if an input Region contains three polygons, and one of those polygons is a Hole in another polygon, then the output will be two Region objects, one of which will contain the hole.

Multiple-section polyline objects will produce new single-section polyline objects. Multi-point objects will produce new Point objects, one Point object per node from the input multi-point.

Collections will be treated recursively. If a Collection contains a Region, then new Region objects will be produced as described above, depending on the All switch. If the Collection contains a polyline object, the new polyline objects will be produced for each section that exists in the input object. If a Collection contains a multi-point, then new Point objects will be produced, one Point object for each node in the multi-point. All other object types, including Points, Lines, Arcs, Rectangles, Rounded Rectangles, and Ellipses, which are already single component objects, will be moved to the output unchanged.

If a Region contains a single polygon, it will be passed unchanged to the output. If a polyline object contains a single section, it will be passed unchanged to the output. If a multi-point object contains a single node, the output object will be changed into a Point object containing that node. Arcs, Rectangles, Rounded Rectangles, and Ellipses will be passed unchanged to the output. Other object types, such as Text, will not be accepted by the Objects Disaggregate statement, and will produce an error.

The Collection keyword will only break up Collection objects. If a Collection object contains a Region, then that Region will be a new object on output. If a Collection object contains a polyline, then that polyline will be a new object in the output. If a Collection object contains a multi-point, then that multi-point will be a new object in the output. This differs from the above functionality since the output Region may contain multiple polygons, the output polyline may contain multiple segments. The functionality above will never produce a multi-point object.

With the Collection keyword, all other object types, including points, multi-points, lines, polylines, arcs, regions, rectangles, rounded rectangles, and ellipses, will be passed to the output unchanged.

If no Into Table is provided, the currently editable table is used as the output table. The input objects are taken from the current selection.

The optional Data clause controls what values are stored in the columns of the target objects. The Data clause can contain a comma-separated list of column assignments. Each column assignment can take one of the forms listed in the following table:

col_name = col_name

col_name = value

col_name = Proportion( col_name )

The Data clause can contain an assignment for every column in the table. If the Data clause only specifies assignments for some of the columns, blank values are assigned to those columns that are not listed in the Data clause. If you omit the Data clause entirely, all columns are blanked out of the target objects, storing zero values in numeric columns and blank values in character columns.

Specifying that the DropIndex clause is On suspends updating transaction indexes while executing the operation and recreates them when the operation is complete. In some cases this significantly improves performance, but not always. For the best performance, we recommend setting this clause to Auto, so that MapInfo Pro decides whether or not to suspend and recreate indexes. MapInfo Pro will suspend and recreate indexes later if the operation is deleting or updating the rows and the table contains more than 1000 rows and more than 0.1% of the total rows are getting updated. When the DropIndex clause is Off the operation executes without suspending and recreating the transaction indexes.

Example

Open Table "STATES.TAB" Interactive
Map From STATES
Set Map Layer 1 Editable On
select * from STATES 
Objects Disaggregate Into Table STATES

See Also: