Objects Combine statement - MapBasic - 2023

Purpose

Combines objects in a table; corresponds to MapInfo Pro's Combine command on the SPATIAL tab. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Objects Combine
	[ Into Target ]
	[ Data column = expression [ , column = expression ... ] ]
	[ DropIndex ( Auto | On | Off ) ]

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

expression is an expression used to populate the column.

Description

Objects Combine creates an object representing the geographic union of the currently selected objects. Optionally, Objects Combine can also perform data aggregation, calculating sums or averages of the data values that are associated with the objects being combined.

The Objects Combine statement corresponds to MapInfo Pro's Combine command on the SPATIAL tab. For an introduction to this operation, see the discussion of the Combine command in the MapInfo Pro User Guide. To see a demonstration of the Objects Combine statement, run MapInfo Pro, open the MapBasic window, and use the Combine command (located on the SPATIAL tab). Objects involved in the combine operation must either be all closed objects (for example, regions, rectangles, rounded rectangles, or ellipses) or all linear objects (for example, lines, polylines, or arcs). Mixed closed and linear objects as well as point and text objects are not allowed.

The optional Into Target clause is only valid if an editing target has been specified (either by the user or through the Set Target statement), and only if the target consists of one object. If you include the Into Target clause, MapInfo Pro combines the currently-selected objects with the current target object. The object produced by the combine operation then replaces the object that had been the editing target.

If you include the Into Target clause, and if the selected objects are from the same table as the target object, MapInfo Pro deletes the rows corresponding to the selected objects.

If you include the Into Target clause, and if the selected objects are from a different table than the target object, MapInfo Pro does not delete the selected objects. If you omit the Into Target clause, MapInfo Pro combines the currently-selected objects without involving the current editing target (if there is an editing target). The rows corresponding to the selected objects are deleted, and a new row is added to the table, containing the object produced by the combine operation.

The Data clause controls data aggregation. (For an introduction to data aggregation, see the description of the Combine command in the MapInfo Pro User Guide.) The Data clause includes a comma-separated list of assignments. You can assign any expression to a column, assuming the expression is of the correct data type (numeric, string, etc.).

The following table lists the more common types of column assignments:

col_name = col_name

col_name = value

col_name = Sum( col_name )

col_name = Avg( col_name )

col_name = WtAvg( colname, wtcolname )

The Data clause can contain an assignment for every column in the table. If the Data clause only includes assignments for some of the columns, MapBasic assigns blank values to those columns that are not listed in the Data clause. If you omit the Data clause entirely, but you include the Into Target clause, then MapInfo Pro retains the target object's original column values.

If you omit both the Data clause and the Into Target clause, then the object produced by the combine operation is stored in a new row, and MapInfo Pro assigns blank values to all of the columns of the new row.

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.

See Also:

Combine() function, Set Combine Version statement, Set Target statement