datatable.Frame.key

datatable.Frame.
key
=
newkey
source
del
datatable.Frame.
key

The tuple of column names that are the primary key for this frame.

If the frame has no primary key, this property returns an empty tuple.

The primary key columns are always located at the beginning of the frame, and therefore the following holds:

DT.key == DT.names[:len(DT.key)]

Assigning to this property will make the Frame keyed by the specified column(s). The key columns will be moved to the front, and the Frame will be sorted. The values in the key columns must be unique.

Parameters

return
Tuple[str, ...]

When used as a getter, returns the tuple of names of the primary key columns.

newkey
str | List[str] | Tuple[str, ...] | None

Specify a column or a list of columns that will become the new primary key of the Frame. Object columns cannot be used for a key. The values in the key column must be unique; if multiple columns are assigned as the key, then their combined (tuple-like) values must be unique.

If newkey is None, then this is equivalent to deleting the key. When the key is deleted, the key columns remain in the frame, they merely stop being marked as “key”.

except
ValueError

Raised when the values in the key column(s) are not unique.

except
KeyError

Raised when newkey contains a column name that doesn’t exist in the Frame.

Examples

DT = dt.Frame(A=range(5), B=['one', 'two', 'three', 'four', 'five'])
DT.key = 'B'
DT
BA
▪▪▪▪▪▪▪▪
five4
four3
one0
three2
two1
5 rows × 2 columns