Joining

Files
file	join.hpp

Classes
class	cudf::hash_join
	Hash join that builds hash table in creation and probes results in subsequent *_join member functions. More...

Functions
std::pair< std::unique_ptr< rmm::device_uvector< size_type > >, std::unique_ptr< rmm::device_uvector< size_type > > >	cudf::inner_join (cudf::table_view const &left_keys, cudf::table_view const &right_keys, null_equality compare_nulls=null_equality::EQUAL, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Returns a pair of row index vectors corresponding to an inner join between the specified tables. More...
std::unique_ptr< cudf::table >	cudf::inner_join (cudf::table_view const &left, cudf::table_view const &right, std::vector< cudf::size_type > const &left_on, std::vector< cudf::size_type > const &right_on, null_equality compare_nulls=null_equality::EQUAL, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Performs an inner join on the specified columns of two tables (left, right) More...
std::pair< std::unique_ptr< rmm::device_uvector< size_type > >, std::unique_ptr< rmm::device_uvector< size_type > > >	cudf::left_join (cudf::table_view const &left_keys, cudf::table_view const &right_keys, null_equality compare_nulls=null_equality::EQUAL, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Returns a pair of row index vectors corresponding to a left join between the specified tables. More...
std::unique_ptr< cudf::table >	cudf::left_join (cudf::table_view const &left, cudf::table_view const &right, std::vector< cudf::size_type > const &left_on, std::vector< cudf::size_type > const &right_on, null_equality compare_nulls=null_equality::EQUAL, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Performs a left join (also known as left outer join) on the specified columns of two tables (left, right) More...
std::pair< std::unique_ptr< rmm::device_uvector< size_type > >, std::unique_ptr< rmm::device_uvector< size_type > > >	cudf::full_join (cudf::table_view const &left_keys, cudf::table_view const &right_keys, null_equality compare_nulls=null_equality::EQUAL, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Returns a pair of row index vectors corresponding to a full join between the specified tables. More...
std::unique_ptr< cudf::table >	cudf::full_join (cudf::table_view const &left, cudf::table_view const &right, std::vector< cudf::size_type > const &left_on, std::vector< cudf::size_type > const &right_on, null_equality compare_nulls=null_equality::EQUAL, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Performs a full join (also known as full outer join) on the specified columns of two tables (left, right) More...
std::unique_ptr< rmm::device_uvector< size_type > >	cudf::left_semi_join (cudf::table_view const &left_keys, cudf::table_view const &right_keys, null_equality compare_nulls=null_equality::EQUAL, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Returns a vector of row indices corresponding to a left semi join between the specified tables. More...
std::unique_ptr< cudf::table >	cudf::left_semi_join (cudf::table_view const &left, cudf::table_view const &right, std::vector< cudf::size_type > const &left_on, std::vector< cudf::size_type > const &right_on, null_equality compare_nulls=null_equality::EQUAL, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Performs a left semi join on the specified columns of two tables (left, right) More...
std::unique_ptr< rmm::device_uvector< size_type > >	cudf::left_anti_join (cudf::table_view const &left_keys, cudf::table_view const &right_keys, null_equality compare_nulls=null_equality::EQUAL, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Returns a vector of row indices corresponding to a left anti join between the specified tables. More...
std::unique_ptr< cudf::table >	cudf::left_anti_join (cudf::table_view const &left, cudf::table_view const &right, std::vector< cudf::size_type > const &left_on, std::vector< cudf::size_type > const &right_on, null_equality compare_nulls=null_equality::EQUAL, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Performs a left anti join on the specified columns of two tables (left, right) More...
std::unique_ptr< cudf::table >	cudf::cross_join (cudf::table_view const &left, cudf::table_view const &right, rmm::mr::device_memory_resource *mr=rmm::mr::get_current_device_resource())
	Performs a cross join on two tables (left, right) More...

Detailed Description

Function Documentation

cross_join()

std::unique_ptr<cudf::table> cudf::cross_join	(	cudf::table_view const &	left,
		cudf::table_view const &	right,
		rmm::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Performs a cross join on two tables (left, right)

The cross join returns the cartesian product of rows from each table.

Note

Warning: This function can easily cause out-of-memory errors. The size of the output is equal to left.num_rows() * right.num_rows(). Use with caution.

Left a: {0, 1, 2}
Right b: {3, 4, 5}
Result: { a: {0, 0, 0, 1, 1, 1, 2, 2, 2}, b: {3, 4, 5, 3, 4, 5, 3, 4, 5} }

Exceptions

cudf::logic_error

if the number of columns in either left or right table is 0

Parameters

left	The left table
right	The right table
mr	Device memory resource used to allocate the returned table's device memory

Returns

Result of cross joining left and right tables

full_join() [1/2]

std::unique_ptr<cudf::table> cudf::full_join	(	cudf::table_view const &	left,
		cudf::table_view const &	right,
		std::vector< cudf::size_type > const &	left_on,
		std::vector< cudf::size_type > const &	right_on,
		null_equality	compare_nulls = null_equality::EQUAL,
		rmm::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Performs a full join (also known as full outer join) on the specified columns of two tables (left, right)

Full Join returns the rows that would be returned by a left join and those rows from the right table that do not have a match. For rows from the right table that do not have a match, the corresponding values in the left columns will be null.

Left: {{0, 1, 2}}
Right: {{1, 2, 3}, {1, 2, 5}}
left_on: {0}
right_on: {1}
Result: { {0, 1, 2, NULL}, {NULL, 1, 2, 3}, {NULL, 1, 2, 5} }
 
Left: {{0, 1, 2}}
Right: {{1, 2, 3}, {1, 2, 5}}
left_on: {0}
right_on: {0}
Result: { {0, 1, 2, NULL}, {NULL, 1, 2, 3}, {NULL, 1, 2, 5} }

Exceptions

cudf::logic_error	if number of elements in left_on or right_on mismatch.
cudf::logic_error	if number of columns in either left or right table is 0 or exceeds MAX_JOIN_SIZE
std::out_of_range	if element of left_on or right_on exceed the number of columns in the left or right table.

Parameters

[in]	left	The left table
[in]	right	The right table
[in]	left_on	The column indices from left to join on. The column from left indicated by left_on[i] will be compared against the column from right indicated by right_on[i].
[in]	right_on	The column indices from right to join on. The column from right indicated by right_on[i] will be compared against the column from left indicated by left_on[i].
[in]	compare_nulls	controls whether null join-key values should match or not.
	mr	Device memory resource used to allocate the returned table and columns' device memory

Returns

Result of joining left and right tables on the columns specified by left_on and right_on.

full_join() [2/2]

std::pair<std::unique_ptr<rmm::device_uvector<size_type> >, std::unique_ptr<rmm::device_uvector<size_type> > > cudf::full_join	(	cudf::table_view const &	left_keys,
		cudf::table_view const &	right_keys,
		null_equality	compare_nulls = null_equality::EQUAL,
		rmm::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Returns a pair of row index vectors corresponding to a full join between the specified tables.

Taken pairwise, the values from the returned vectors are one of: (1) row indices corresponding to matching rows from the left and right tables, (2) a row index and an unspecified out-of-bounds value, representing a row from one table without a match in the other.

Left: {{0, 1, 2}}
Right: {{1, 2, 3}}
Result: {{0, 1, 2, None}, {None, 0, 1, 2}}
 
Left: {{0, 1, 2}, {3, 4, 5}}
Right: {{1, 2, 3}, {4, 6, 7}}
Result: {{0, 1, 2, None, None}, {None, 0, None, 1, 2}}

Exceptions

cudf::logic_error

if number of elements in left_keys or right_keys mismatch.

Parameters

[in]	left	The left table
[in]	right	The right table
[in]	compare_nulls	controls whether null join-key values should match or not.
	mr	Device memory resource used to allocate the returned table and columns' device memory

Returns

A pair of vectors [left_indices, right_indices] that can be used to construct the result of performing a full join between two tables with left_keys and right_keys as the join keys .

inner_join() [1/2]

std::unique_ptr<cudf::table> cudf::inner_join	(	cudf::table_view const &	left,
		cudf::table_view const &	right,
		std::vector< cudf::size_type > const &	left_on,
		std::vector< cudf::size_type > const &	right_on,
		null_equality	compare_nulls = null_equality::EQUAL,
		rmm::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Performs an inner join on the specified columns of two tables (left, right)

Inner Join returns rows from both tables as long as the values in the columns being joined on match.

Left: {{0, 1, 2}}
Right: {{4, 9, 3}, {1, 2, 5}}
left_on: {0}
right_on: {1}
Result: {{1, 2}, {4, 9}, {1, 2}}

Exceptions

cudf::logic_error	if number of elements in left_on or right_on mismatch.
cudf::logic_error	if number of columns in either left or right table is 0 or exceeds MAX_JOIN_SIZE
std::out_of_range	if element of left_on or right_on exceed the number of columns in the left or right table.

Parameters

[in]	left	The left table
[in]	right	The right table
[in]	left_on	The column indices from left to join on. The column from left indicated by left_on[i] will be compared against the column from right indicated by right_on[i].
[in]	right_on	The column indices from right to join on. The column from right indicated by right_on[i] will be compared against the column from left indicated by left_on[i].
[in]	compare_nulls	controls whether null join-key values should match or not.
	mr	Device memory resource used to allocate the returned table and columns' device memory

Returns

Result of joining left and right tables on the columns specified by left_on and right_on.

inner_join() [2/2]

std::pair<std::unique_ptr<rmm::device_uvector<size_type> >, std::unique_ptr<rmm::device_uvector<size_type> > > cudf::inner_join	(	cudf::table_view const &	left_keys,
		cudf::table_view const &	right_keys,
		null_equality	compare_nulls = null_equality::EQUAL,
		rmm::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Returns a pair of row index vectors corresponding to an inner join between the specified tables.

The first returned vector contains the row indices from the left table that have a match in the right table (in unspecified order). The corresponding values in the second returned vector are the matched row indices from the right table.

Left: {{0, 1, 2}}
Right: {{1, 2, 3}}
Result: {{1, 2}, {0, 1}}
 
Left: {{0, 1, 2}, {3, 4, 5}}
Right: {{1, 2, 3}, {4, 6, 7}}
Result: {{1}, {0}}

Exceptions

cudf::logic_error

if number of elements in left_keys or right_keys mismatch.

Parameters

[in]	left_keys	The left table
[in]	right_keys	The right table
[in]	compare_nulls	controls whether null join-key values should match or not.
	mr	Device memory resource used to allocate the returned table and columns' device memory

Returns

A pair of vectors [left_indices, right_indices] that can be used to construct the result of performing an inner join between two tables with left_keys and right_keys as the join keys .

left_anti_join() [1/2]

std::unique_ptr<cudf::table> cudf::left_anti_join	(	cudf::table_view const &	left,
		cudf::table_view const &	right,
		std::vector< cudf::size_type > const &	left_on,
		std::vector< cudf::size_type > const &	right_on,
		null_equality	compare_nulls = null_equality::EQUAL,
		rmm::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Performs a left anti join on the specified columns of two tables (left, right)

A left anti join only returns data from the left table, and only returns rows that do not exist in the right table.

TableA: {{0, 1, 2}}
TableB: {{1, 2, 3},  {1, 2, 5}}
left_on: {0}
right_on: {1}
Result: {{0}, {1}}
 
TableA: {{0, 1, 2}, {1, 2, 5}}
TableB: {{1, 2, 3}}
left_on: {0}
right_on: {0}
Result: { {0} {1} }

Exceptions

cudf::logic_error	if number of elements in left_on or right_on mismatch.
cudf::logic_error	if number of columns in either left or right table is 0 or exceeds MAX_JOIN_SIZE

Parameters

[in]	left	The left table
[in]	right	The right table
[in]	left_on	The column indices from left to join on. The column from left indicated by left_on[i] will be compared against the column from right indicated by right_on[i].
[in]	right_on	The column indices from right to join on. The column from right indicated by right_on[i] will be compared against the column from left indicated by left_on[i].
[in]	compare_nulls	Controls whether null join-key values should match or not.
[in]	mr	Device memory resource used to allocate the returned table's device memory

Returns

Result of joining left and right tables on the columns specified by left_on and right_on.

left_anti_join() [2/2]

std::unique_ptr<rmm::device_uvector<size_type> > cudf::left_anti_join	(	cudf::table_view const &	left_keys,
		cudf::table_view const &	right_keys,
		null_equality	compare_nulls = null_equality::EQUAL,
		rmm::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Returns a vector of row indices corresponding to a left anti join between the specified tables.

The returned vector contains the row indices from the left table for which there is no matching row in the right table.

TableA: {{0, 1, 2}}
TableB: {{1, 2, 3}}
Result: {0}

Exceptions

cudf::logic_error

if the number of columns in either left_keys or right_keys is 0

Parameters

[in]	left_keys	The left table
[in]	right_keys	The right table
[in]	compare_nulls	controls whether null join-key values should match or not.
	mr	Device memory resource used to allocate the returned table and columns' device memory

Returns

A column left_indices that can be used to construct the result of performing a left anti join between two tables with left_keys and right_keys as the join keys .

left_join() [1/2]

std::unique_ptr<cudf::table> cudf::left_join	(	cudf::table_view const &	left,
		cudf::table_view const &	right,
		std::vector< cudf::size_type > const &	left_on,
		std::vector< cudf::size_type > const &	right_on,
		null_equality	compare_nulls = null_equality::EQUAL,
		rmm::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Performs a left join (also known as left outer join) on the specified columns of two tables (left, right)

Left join returns all the rows from the left table and those rows from the right table that match on the joined columns. For rows from the right table that do not have a match, the corresponding values in the left columns will be null.

Left: {{0, 1, 2}}
Right: {{1, 2, 3}, {1, 2 ,5}}
left_on: {0}
right_on: {1}
Result: { {0, 1, 2}, {NULL, 1, 2}, {NULL, 1, 2} }
 
Left: {{0, 1, 2}}
Right {{1, 2, 3}, {1, 2, 5}}
left_on: {0}
right_on: {0}
Result: { {0, 1, 2}, {NULL, 1, 2}, {NULL, 1, 2} }

Exceptions

cudf::logic_error	if number of elements in left_on or right_on mismatch.
cudf::logic_error	if number of columns in either left or right table is 0 or exceeds MAX_JOIN_SIZE
std::out_of_range	if element of left_on or right_on exceed the number of columns in the left or right table.

Parameters

[in]	left	The left table
[in]	right	The right table
[in]	left_on	The column indices from left to join on. The column from left indicated by left_on[i] will be compared against the column from right indicated by right_on[i].
[in]	right_on	The column indices from right to join on. The column from right indicated by right_on[i] will be compared against the column from left indicated by left_on[i].
[in]	compare_nulls	controls whether null join-key values should match or not.
	mr	Device memory resource used to allocate the returned table and columns' device memory

Returns

Result of joining left and right tables on the columns specified by left_on and right_on.

left_join() [2/2]

std::pair<std::unique_ptr<rmm::device_uvector<size_type> >, std::unique_ptr<rmm::device_uvector<size_type> > > cudf::left_join	(	cudf::table_view const &	left_keys,
		cudf::table_view const &	right_keys,
		null_equality	compare_nulls = null_equality::EQUAL,
		rmm::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Returns a pair of row index vectors corresponding to a left join between the specified tables.

The first returned vector contains all the row indices from the left table (in unspecified order). The corresponding value in the second returned vector is either (1) the row index of the matched row from the right table, if there is a match or (2) an unspecified out-of-bounds value.

Left: {{0, 1, 2}}
Right: {{1, 2, 3}}
Result: {{0, 1, 2}, {None, 0, 1}}
 
Left: {{0, 1, 2}, {3, 4, 5}}
Right: {{1, 2, 3}, {4, 6, 7}}
Result: {{0, 1, 2}, {None, 0, None}}

Exceptions

cudf::logic_error

if number of elements in left_keys or right_keys mismatch.

Parameters

[in]	left_keys	The left table
[in]	right_keys	The right table
[in]	compare_nulls	controls whether null join-key values should match or not.
	mr	Device memory resource used to allocate the returned table and columns' device memory

Returns

A pair of vectors [left_indices, right_indices] that can be used to construct the result of performing a left join between two tables with left_keys and right_keys as the join keys .

left_semi_join() [1/2]

std::unique_ptr<cudf::table> cudf::left_semi_join	(	cudf::table_view const &	left,
		cudf::table_view const &	right,
		std::vector< cudf::size_type > const &	left_on,
		std::vector< cudf::size_type > const &	right_on,
		null_equality	compare_nulls = null_equality::EQUAL,
		rmm::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Performs a left semi join on the specified columns of two tables (left, right)

A left semi join only returns data from the left table, and only returns rows that exist in the right table.

TableA: {{0, 1, 2}}
TableB: {{1, 2, 3}, {1, 2, 5}}
left_on: {0}
right_on: {1}
Result: { {1, 2} }
 
TableA {{0, 1, 2}, {1, 2, 5}}
TableB {{1, 2, 3}}
left_on: {0}
right_on: {0}
Result: { {1, 2}, {2, 5} }

Exceptions

cudf::logic_error

if the number of columns in either left_keys or right_keys is 0

Parameters

[in]	left	The left table
[in]	right	The right table
[in]	left_on	The column indices from left to join on. The column from left indicated by left_on[i] will be compared against the column from right indicated by right_on[i].
[in]	right_on	The column indices from right to join on. The column from right indicated by right_on[i] will be compared against the column from left indicated by left_on[i].
[in]	compare_nulls	Controls whether null join-key values should match or not.
[in]	mr	Device memory resource used to allocate the returned table's device memory

Returns

Result of joining left and right tables on the columns specified by left_on and right_on.

left_semi_join() [2/2]

std::unique_ptr<rmm::device_uvector<size_type> > cudf::left_semi_join	(	cudf::table_view const &	left_keys,
		cudf::table_view const &	right_keys,
		null_equality	compare_nulls = null_equality::EQUAL,
		rmm::mr::device_memory_resource *	mr = rmm::mr::get_current_device_resource()
	)

Returns a vector of row indices corresponding to a left semi join between the specified tables.

The returned vector contains the row indices from the left table for which there is a matching row in the right table.

TableA: {{0, 1, 2}}
TableB: {{1, 2, 3}}
right_on: {1}
Result: {1, 2}

Exceptions

cudf::logic_error

if number of columns in either left_keys or right_keys table is 0 or exceeds MAX_JOIN_SIZE

Parameters

[in]	left_keys	The left table
[in]	right_keys	The right table
[in]	compare_nulls	controls whether null join-key values should match or not.
	mr	Device memory resource used to allocate the returned table and columns' device memory

Returns

A vector left_indices that can be used to construct the result of performing a left semi join between two tables with left_keys and right_keys as the join keys .