C Interfaces#

ABI Structures#

struct ArrowSchema#

struct ArrowArray#

struct ArrowArrayStream#

C Data Interface#

Status ExportType(const DataType &type, struct ArrowSchema *out)#

Export C++ DataType using the C data interface format.

The root type is considered to have empty name and metadata. If you want the root type to have a name and/or metadata, pass a Field instead.

Parameters:

type – [in] DataType object to export
out – [out] C struct where to export the datatype

Status ExportField(const Field &field, struct ArrowSchema *out)#

Export C++ Field using the C data interface format.

Parameters:

field – [in] Field object to export
out – [out] C struct where to export the field

Status ExportSchema(const Schema &schema, struct ArrowSchema *out)#

Export C++ Schema using the C data interface format.

Parameters:

schema – [in] Schema object to export
out – [out] C struct where to export the field

Status ExportArray(const Array &array, struct ArrowArray *out, struct ArrowSchema *out_schema = NULLPTR)#

Export C++ Array using the C data interface format.

The resulting ArrowArray struct keeps the array data and buffers alive until its release callback is called by the consumer.

Parameters:

array – [in] Array object to export
out – [out] C struct where to export the array
out_schema – [out] optional C struct where to export the array type

Status ExportRecordBatch(const RecordBatch &batch, struct ArrowArray *out, struct ArrowSchema *out_schema = NULLPTR)#

Export C++ RecordBatch using the C data interface format.

The record batch is exported as if it were a struct array. The resulting ArrowArray struct keeps the record batch data and buffers alive until its release callback is called by the consumer.

Parameters:

batch – [in] Record batch to export
out – [out] C struct where to export the record batch
out_schema – [out] optional C struct where to export the record batch schema

Result<std::shared_ptr<DataType>> ImportType(struct ArrowSchema *schema)#

Import C++ DataType from the C data interface.

The given ArrowSchema struct is released (as per the C data interface specification), even if this function fails.

Parameters:: schema – [inout] C data interface struct representing the data type
Returns:: Imported type object

Result<std::shared_ptr<Field>> ImportField(struct ArrowSchema *schema)#

Import C++ Field from the C data interface.

The given ArrowSchema struct is released (as per the C data interface specification), even if this function fails.

Parameters:: schema – [inout] C data interface struct representing the field
Returns:: Imported field object

Result<std::shared_ptr<Schema>> ImportSchema(struct ArrowSchema *schema)#

Import C++ Schema from the C data interface.

The given ArrowSchema struct is released (as per the C data interface specification), even if this function fails.

Parameters:: schema – [inout] C data interface struct representing the field
Returns:: Imported field object

Result<std::shared_ptr<Array>> ImportArray(struct ArrowArray *array, std::shared_ptr<DataType> type)#

Import C++ array from the C data interface.

The ArrowArray struct has its contents moved (as per the C data interface specification) to a private object held alive by the resulting array.

Parameters:

array – [inout] C data interface struct holding the array data
type – [in] type of the imported array

Returns:

Imported array object

Result<std::shared_ptr<Array>> ImportArray(struct ArrowArray *array, struct ArrowSchema *type)#

Import C++ array and its type from the C data interface.

The ArrowArray struct has its contents moved (as per the C data interface specification) to a private object held alive by the resulting array. The ArrowSchema struct is released, even if this function fails.

Parameters:

array – [inout] C data interface struct holding the array data
type – [inout] C data interface struct holding the array type

Returns:

Imported array object

Result<std::shared_ptr<RecordBatch>> ImportRecordBatch(struct ArrowArray *array, std::shared_ptr<Schema> schema)#

Import C++ record batch from the C data interface.

The ArrowArray struct has its contents moved (as per the C data interface specification) to a private object held alive by the resulting record batch.

Parameters:

array – [inout] C data interface struct holding the record batch data
schema – [in] schema of the imported record batch

Returns:

Imported record batch object

Result<std::shared_ptr<RecordBatch>> ImportRecordBatch(struct ArrowArray *array, struct ArrowSchema *schema)#

Import C++ record batch and its schema from the C data interface.

The type represented by the ArrowSchema struct must be a struct type array. The ArrowArray struct has its contents moved (as per the C data interface specification) to a private object held alive by the resulting record batch. The ArrowSchema struct is released, even if this function fails.

Parameters:

array – [inout] C data interface struct holding the record batch data
schema – [inout] C data interface struct holding the record batch schema

Returns:

Imported record batch object

C Stream Interface#

Status ExportRecordBatchReader(std::shared_ptr<RecordBatchReader> reader, struct ArrowArrayStream *out)#

Export C++ RecordBatchReader using the C stream interface.

The resulting ArrowArrayStream struct keeps the record batch reader alive until its release callback is called by the consumer.

Parameters:

reader – [in] RecordBatchReader object to export
out – [out] C struct where to export the stream

Status ExportChunkedArray(std::shared_ptr<ChunkedArray> chunked_array, struct ArrowArrayStream *out)#

Export C++ ChunkedArray using the C data interface format.

The resulting ArrowArrayStream struct keeps the chunked array data and buffers alive until its release callback is called by the consumer.

Parameters:

chunked_array – [in] ChunkedArray object to export
out – [out] C struct where to export the stream

Status ExportDeviceRecordBatchReader(std::shared_ptr<RecordBatchReader> reader, struct ArrowDeviceArrayStream *out)#

Export C++ RecordBatchReader using the C device stream interface.

The resulting ArrowDeviceArrayStream struct keeps the record batch reader alive until its release callback is called by the consumer. The device type is determined by calling device_type() on the RecordBatchReader.

Parameters:

reader – [in] RecordBatchReader object to export
out – [out] C struct to export the stream to

Status ExportDeviceChunkedArray(std::shared_ptr<ChunkedArray> chunked_array, DeviceAllocationType device_type, struct ArrowDeviceArrayStream *out)#

Export C++ ChunkedArray using the C device data interface format.

The resulting ArrowDeviceArrayStream keeps the chunked array data and buffers alive until its release callback is called by the consumer.

Parameters:

chunked_array – [in] ChunkedArray object to export
device_type – [in] the device type the data is located on
out – [out] C struct to export the stream to

Result<std::shared_ptr<RecordBatchReader>> ImportRecordBatchReader(struct ArrowArrayStream *stream)#

Import C++ RecordBatchReader from the C stream interface.

The ArrowArrayStream struct has its contents moved to a private object held alive by the resulting record batch reader.

Parameters:: stream – [inout] C stream interface struct
Returns:: Imported RecordBatchReader object

Result<std::shared_ptr<ChunkedArray>> ImportChunkedArray(struct ArrowArrayStream *stream)#

Import C++ ChunkedArray from the C stream interface.

The ArrowArrayStream struct has its contents moved to a private object, is consumed in its entirity, and released before returning all chunks as a ChunkedArray.

Parameters:: stream – [inout] C stream interface struct
Returns:: Imported ChunkedArray object

Result<std::shared_ptr<RecordBatchReader>> ImportDeviceRecordBatchReader(struct ArrowDeviceArrayStream *stream, const DeviceMemoryMapper &mapper = DefaultDeviceMemoryMapper)#

Import C++ RecordBatchReader from the C device stream interface.

The ArrowDeviceArrayStream struct has its contents moved to a private object held alive by the resulting record batch reader.

Note

If there was a required sync event, sync events are accessible by individual buffers of columns. We are not yet bubbling the sync events from the buffers up to the GetSyncEvent method of an imported RecordBatch. This will be added in a future update.

Parameters:

stream – [inout] C device stream interface struct
mapper – [in] mapping from device type and ID to memory manager

Returns:

Imported RecordBatchReader object

Result<std::shared_ptr<ChunkedArray>> ImportDeviceChunkedArray(struct ArrowDeviceArrayStream *stream, const DeviceMemoryMapper &mapper = DefaultDeviceMemoryMapper)#

Import C++ ChunkedArray from the C device stream interface.

The ArrowDeviceArrayStream struct has its contents moved to a private object, is consumed in its entirety, and released before returning all chunks as a ChunkedArray.

Note

Any chunks that require synchronization for their device memory will have the SyncEvent objects available by checking the individual buffers of each chunk. These SyncEvents should be checked before accessing the data in those buffers.

Parameters:

stream – [inout] C device stream interface struct
mapper – [in] mapping from device type and ID to memory manager

Returns:

Imported ChunkedArray object