Преобразование между DuckDB и Python

Эта страница документирует правила преобразования объектов Python в DuckDB и результатов DuckDB в Python.

Преобразование объектов: Объект Python в DuckDB

Это сопоставление типов объектов Python с логическими типами DuckDB Logical Types:

• None → NULL
• bool → BOOLEAN
• datetime.timedelta → INTERVAL
• str → VARCHAR
• bytearray → BLOB
• memoryview → BLOB
• decimal.Decimal → DECIMAL / DOUBLE
• uuid.UUID → UUID

Остальные правила преобразования следующие.

int

Поскольку целые числа в Python могут иметь произвольную длину, точного взаимного преобразования для целых чисел невозможно. Вместо этого мы выполняем эти преобразования в заданном порядке, пока одно из них не удастся:

• BIGINT
• INTEGER
• UBIGINT
• UINTEGER
• DOUBLE

При использовании класса DuckDB Value можно задать целевой тип, который повлияет на преобразование.

float

Эти преобразования пробуются в порядке, пока одно не удастся:

• DOUBLE
• FLOAT

datetime.datetime

Для datetime мы проверим pandas.isnull , если оно доступно, и вернём NULL , если оно вернёт true. Мы проверим на datetime.datetime.min и datetime.datetime.max для преобразования в -inf и +inf соответственно.

Если у datetime есть tzinfo, мы будем использовать TIMESTAMPTZ, иначе оно станет TIMESTAMP.

datetime.time

Если у time есть tzinfo, мы будем использовать TIMETZ, иначе оно станет TIME.

datetime.date

date преобразуется в тип DATE. Мы проверим на datetime.date.min и datetime.date.max для преобразования в -inf и +inf соответственно.

bytes

bytes преобразуется в BLOB по умолчанию, когда используется для создания объекта Value типа BITSTRING, он преобразуется в BITSTRING.

list

list становится типом LIST «наиболее допустимого» типа из своих дочерних элементов, например:

my_list_value = [
    12345,
    "test"
]

Преобразуется в VARCHAR[], потому что 12345 может преобразовываться в VARCHAR, но test не может преобразовываться в INTEGER.

[12345, test]

dict

Объект dict может быть преобразован в STRUCT(...) или MAP(..., ...) в зависимости от его структуры. Если у словаря есть структура, подобная:

my_map_dict = {
    "key": [
        1, 2, 3
    ],
    "value": [
        "one", "two", "three"
    ]
}

Тогда он преобразуется в MAP пар ключ-значение из двух списков, соединённых вместе. Приведённый выше пример становится MAP(INTEGER, VARCHAR):

{1=one, 2=two, 3=three}

Имена полей важны, и два списка должны иметь одинаковый размер.

В противном случае мы попытаемся преобразовать его в STRUCT.

my_struct_dict = {
    1: "one",
    "2": 2,
    "three": [1, 2, 3],
    False: True
}

Преобразуется в:

{'1': one, '2': 2, 'three': [1, 2, 3], 'False': true}

Каждое key словаря преобразуется в строку.

tuple

tuple преобразуется в LIST по умолчанию, а при использовании для создания объекта Value типа STRUCT он преобразуется в STRUCT.

numpy.ndarray и numpy.datetime64

ndarray и datetime64 преобразуются путём вызова tolist() и преобразования результата.

Преобразование результатов: Результаты DuckDB в Python

Python-клиент DuckDB предоставляет несколько дополнительных методов, которые могут быть использованы для эффективного извлечения данных.

NumPy

• fetchnumpy() извлекает данные как словарь массивов NumPy

Pandas

• df() извлекает данные как таблицу Pandas DataFrame
• fetchdf() является псевдонимом df()
• fetch_df() является псевдонимом df()
• fetch_df_chunk(vector_multiple) извлекает часть результатов в DataFrame. Количество строк, возвращаемых в каждом блоке, равно размеру вектора (по умолчанию 2048) * vector_multiple (по умолчанию 1).

Apache Arrow

• arrow() извлекает данные как таблицу Arrow
• fetch_arrow_table() является псевдонимом arrow()
• fetch_record_batch(chunk_size) возвращает чтец партий записей Arrow с chunk_size строками в каждой партии

Polars

• pl() извлекает данные как таблицу Polars DataFrame

Примеры

Ниже приведены некоторые примеры использования этой функциональности. Смотрите руководства по Python для получения дополнительных примеров.

Извлечь как таблицу Pandas DataFrame:

df = con.execute("SELECT * FROM items").fetchdf()
print(df)

item   value  count
0     jeans    20.0      1
1    hammer    42.2      2
2    laptop  2000.0      1
3  chainsaw   500.0     10
4    iphone   300.0      2

Извлечь как словарь массивов NumPy:

arr = con.execute("SELECT * FROM items").fetchnumpy()
print(arr)

{'item': masked_array(data=['jeans', 'hammer', 'laptop', 'chainsaw', 'iphone'],
             mask=[False, False, False, False, False],
       fill_value='?',
            dtype=object), 'value': masked_array(data=[20.0, 42.2, 2000.0, 500.0, 300.0],
             mask=[False, False, False, False, False],
       fill_value=1e+20), 'count': masked_array(data=[1, 2, 1, 10, 2],
             mask=[False, False, False, False, False],
       fill_value=999999,
            dtype=int32)}

Извлечь как таблицу Arrow. Преобразование в Pandas после для красивого вывода:

tbl = con.execute("SELECT * FROM items").fetch_arrow_table()
print(tbl.to_pandas())

item    value  count
0     jeans    20.00      1
1    hammer    42.20      2
2    laptop  2000.00      1
3  chainsaw   500.00     10
4    iphone   300.00      2