join
Combine two tables or timetables by rows using key variables
Description
combines the tables or timetables T
= join(Tleft
,Tright
)Tleft
and
Tright
by merging rows from the two inputs. The
join
function performs a simple form of the join operation
where each row of Tleft
must match exactly one row in
Tright
. Rows match where the corresponding values in the
key variables are the
same. The output combines all rows from Tleft
with the rows from
Tright
where the key variables have matching values.
For example, if Tleft
has variables named
Key1
and Var1
, and
Tright
has variables Key1
and
Var2
, then T=join(Tleft,Tright)
uses
Key1
as a key variable.
By default, the key variables are:
Variables that have the same names in
Tleft
andTright
, if both inputs are tables, or ifTleft
is a timetable andTright
is a table.Vectors of row times, if both
Tleft
andTright
are timetables.
The matching values of the key variables do not have to be in the same orders in
the left and right inputs. Also, the key variables of Tright
must
contain all values in the key variables of Tleft
. Each value must
occur only once in the key variables of Tright
, but can occur
multiple times in the key variables of Tleft
. Therefore, the join
operation replicates any row from Tright
that matches multiple
rows from Tleft
.
The inputs can be tables, timetables, or one of each.
If
Tleft
is a table, thenjoin
returnsT
as a table.If
Tleft
is a timetable, thenjoin
returnsT
as a timetable.
joins the tables or timetables with additional options specified by one or more
T
= join(Tleft
,Tright
,Name,Value
)Name,Value
pair arguments.
For example, you can specify which variables to use as key variables.
Examples
Input Arguments
Name-Value Arguments
Output Arguments
More About
Algorithms
The join
function first finds one or more key variables. Then,
join
uses the key variables to find the row in input table
Tright
that matches each row in input table
Tleft
, and combines those rows to create a row in output table
T
.
If there is a one-to-one mapping between key values in
Tleft
andTright
, thenjoin
sorts the data inTright
and appends it to tableTleft
.If there is a many-to-one mapping between key values in
Tleft
andTright
, thenjoin
sorts and repeats the data inTright
before appending it to tableTleft
.If there is data in a key variable of
Tright
that does not map to a key value inTleft
, thenjoin
does not include that data in the output table,T
.
Extended Capabilities
Version History
Introduced in R2013b