As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

API Reference

Pandas Data Types for SQL systems (BigQuery, Spanner)

class db_dtypes.DateArray(values, dtype=None, copy: bool = False)

Pandas array type containing date data

__arrow_array__(type=None)

Convert to an Arrow array from dbdate data.

See: https://pandas.pydata.org/pandas-docs/stable/development/extending.html#compatibility-with-apache-arrow

astype(dtype, copy=True)

Cast to a NumPy array or ExtensionArray with ‘dtype’.

Parameters

• dtype (str or dtype) – Typecode or data-type to which the array is cast.

• copy (bool, default True) – Whether to copy the data, even if not necessary. If False, a copy is made only if the old dtype does not match the new dtype.

Returns

An ExtensionArray if dtype is ExtensionDtype, otherwise a Numpy ndarray with dtype for its dtype.

Return type

np.ndarray or pandas.api.extensions.ExtensionArray

Examples

>>> arr = pd.array([1, 2, 3])
>>> arr
<IntegerArray>
[1, 2, 3]
Length: 3, dtype: Int64

Casting to another ExtensionDtype returns an ExtensionArray:

>>> arr1 = arr.astype('Float64')
>>> arr1
<FloatingArray>
[1.0, 2.0, 3.0]
Length: 3, dtype: Float64
>>> arr1.dtype
Float64Dtype()

Otherwise, we will get a Numpy ndarray:

>>> arr2 = arr.astype('float64')
>>> arr2
array([1., 2., 3.])
>>> arr2.dtype
dtype('float64')

class db_dtypes.DateDtype

Extension dtype for time data.

static __from_arrow__(array: Union[pyarrow.lib.Array, pyarrow.lib.ChunkedArray]) → db_dtypes.DateArray

Convert to dbdate data from an Arrow array.

See: https://pandas.pydata.org/pandas-docs/stable/development/extending.html#compatibility-with-apache-arrow

construct_array_type()

Return the array type associated with this dtype.

Return type

type

type

alias of datetime.date

class db_dtypes.JSONArray(values)

Extension array that handles BigQuery JSON data, leveraging a string-based pyarrow array for storage. It enables seamless conversion to JSON objects when accessing individual elements.

__array__(dtype=None, copy: Optional[bool] = None) → numpy.ndarray

Correctly construct numpy arrays when passed to np.asarray().

__arrow_array__(type=None)

Convert to an arrow array. This is required for pyarrow extension.

__getitem__(item)

Select a subset of self.

__iter__()

Iterate over elements of the array.

property dtype: db_dtypes.json.JSONDtype

An instance of JSONDtype

property pa_data

An instance of stored pa data

class db_dtypes.JSONArrowType

Arrow extension type for the dbjson Pandas extension type.

Initialize an extension type instance.

This should be called at the end of the subclass’ __init__ method.

to_pandas_dtype(self)

Return the equivalent NumPy / Pandas dtype.

Examples

>>> import pyarrow as pa
>>> pa.int64().to_pandas_dtype()
<class 'numpy.int64'>

class db_dtypes.JSONDtype

Extension dtype for BigQuery JSON data.

__from_arrow__(array: pyarrow.lib.Array | pyarrow.lib.ChunkedArray) → db_dtypes.json.JSONArray

Convert the pyarrow array to the extension array.

classmethod construct_array_type()

Return the array type associated with this dtype.

property na_value: pd.NA

Default NA value to use for this type.

property pyarrow_dtype

Return the pyarrow data type used for storing data in the pyarrow array.

property type: type[str]

Return the scalar type for the array elements. The standard JSON data types can be one of dict, list, str, int, float, bool and None. However, this method returns a str type to indicate its storage type, because the union of multiple types are not supported well in pandas.

class db_dtypes.TimeArray(values, dtype=None, copy: bool = False)

Pandas array type containing time data

__arrow_array__(type=None)

Convert to an Arrow array from dbtime data.

See: https://pandas.pydata.org/pandas-docs/stable/development/extending.html#compatibility-with-apache-arrow

astype(dtype, copy=True)

Cast to a NumPy array or ExtensionArray with ‘dtype’.

Parameters

• dtype (str or dtype) – Typecode or data-type to which the array is cast.

• copy (bool, default True) – Whether to copy the data, even if not necessary. If False, a copy is made only if the old dtype does not match the new dtype.

Returns

An ExtensionArray if dtype is ExtensionDtype, otherwise a Numpy ndarray with dtype for its dtype.

Return type

np.ndarray or pandas.api.extensions.ExtensionArray

Examples

>>> arr = pd.array([1, 2, 3])
>>> arr
<IntegerArray>
[1, 2, 3]
Length: 3, dtype: Int64

Casting to another ExtensionDtype returns an ExtensionArray:

>>> arr1 = arr.astype('Float64')
>>> arr1
<FloatingArray>
[1.0, 2.0, 3.0]
Length: 3, dtype: Float64
>>> arr1.dtype
Float64Dtype()

Otherwise, we will get a Numpy ndarray:

>>> arr2 = arr.astype('float64')
>>> arr2
array([1., 2., 3.])
>>> arr2.dtype
dtype('float64')

class db_dtypes.TimeDtype

Extension dtype for time data.

static __from_arrow__(array: Union[pyarrow.lib.Array, pyarrow.lib.ChunkedArray]) → db_dtypes.TimeArray

Convert to dbtime data from an Arrow array.

See: https://pandas.pydata.org/pandas-docs/stable/development/extending.html#compatibility-with-apache-arrow

construct_array_type()

Return the array type associated with this dtype.

Return type

type

type

alias of datetime.time