Функции модуля Python tngri

Для удобной работы с данными в ячейках типа Python создан модуль tngri. В нем доступны функции, описанные на этой странице.

Функции модуля tngri доступны только в ячейках типа Python, и для их работы необходимо импортировать модуль: import tngri.

tngri.create_table()

Описание

Создает таблицу и наполняет ее данными из DataFrame.
Использование

tngri.create_table(data: pandas.DataFrame | polars.DataFrame, table_name: str, replace: bool=False)

Создает таблицу c указанным именем и наполняет ее данными из указанного DataFrame.

DataFrame может иметь как тип Pandas, так и тип Polars.

Параметры

data: pandas.DataFrame | polars.DataFrame

DataFrame с данными для создания таблицы.

table_name: str

Имя создаваемой таблицы. Задается текстовой строкой с опциональным префиксом через . для указания схемы. При отсутствии префикса таблица создается в дефолтной для пользователя схеме.

replace: bool, default False

Опциональный параметр — следует ли заменить таблицу, если она уже существует. По умолчанию не следует.

Посмотреть пример 
import tngri
import pandas as pd

df = pd.DataFrame(
    [
        {"Country": "Russia", "Capital": "Moscow"},
        {"Country": "Italy", "Capital": "Rome"},
    ]
)

tngri.create_table(df, 'demo.capitals', replace=True)
done at 2026-02-11 17:39:06.378942
SELECT * FROM demo.capitals
+---------+---------+
| Country | Capital |
+---------+---------+
| Russia  | Moscow  |
+---------+---------+
| Italy   | Rome    |
+---------+---------+

tngri.delete_file()

Описание

Удаляет файл по заданному пути.
Использование

tngri.delete_file(file: str)
Для удаления всех файлов в директории используйте в комбинации с функцией tngri.list_files().

Параметры

file: str

Путь к файлу для удаления.

Посмотреть пример

Пройдем по всем файлам в директории test и удалим их:

import tngri

for file in tngri.list_files('test/'):
    print(file)
    tngri.delete_file(file)
StagedFile(path=test/my_file.parquet size=734 modified=2026-04-16 10:24:51.755000+00:00)
StagedFile(path=test/my_file_2.parquet size=734 modified=2026-04-16 10:24:56.399000+00:00)

tngri.list_files()

Описание

Выводит список файлов по заданному пути.
Использование

tngri.list_files(filepath: str="")

Выводит список файлов, загруженных в Tengri по заданному пути.

В списке файлов выводятся:

  • Имя и путь к файлу

  • Размер файла

  • Время последнего изменения

Функцию удобно использовать для просмотра всех файлов в заданной директории и удаления ненужных.

Параметры

filepath: str, default ""

Путь к директории. По умолчанию — пустая строка (корень файловой системы).

Посмотреть пример 
import tngri

tngri.list_files('test/')
[StagedFile(path=test/my_file.parquet size=734 modified=2026-04-16 10:11:40.288000+00:00),
 StagedFile(path=test/test.json size=6174 modified=2026-04-16 09:57:14.179000+00:00)]

tngri.run_notebook()

Описание

Запускает указанный ноутбук из другого ноутбука.
Использование

tngri.run_notebook(notebook_id: str)

Запускает указанный ноутбук из другого ноутбука. Возвращает результаты выполнения всех ячеек запущенного ноутбука в виде объекта RunStatus с полями:

  • ok: bool — Был ли запуск успешным

  • output: str — Результаты вывода всех ячеек типа Python

  • errors: str — Текст ошибок

Для того, чтобы ноутбук можно было запускать из другого, он должен быть опубликован (кнопка Publish).

Функцией удобно пользоваться при необходимости оркестрации запусков нескольких ноутбуков. С ее помощью можно реализовать разную логику:

  • Запуск ноутбука по условию

  • Запуск ноутбука сразу после выполнения другого ноутбука

  • Выделение части вычислений в отдельный ноутбук и запуск этой части из других ноутбуков

Параметры

notebook_id: str

Путь и имя ноутбука для запуска.

Посмотреть пример 
import tngri

result = tngri.run_notebook('my_folder/My Notebook')

print(result)
RunStatus(ok=True, output='Output of cell 1 of My Notebook\nOutput of cell 2 of My Notebook\ndone at 2025-12-19 14:02:02.933882', errors='')
done at 2025-12-12 14:09:14.497666

tngri.sql()

Описание

Выполняет указанный запрос SQL внутри ячейки типа Python.
Использование

tngri.sql(sql: str)

Выполняет указанный запрос SQL внутри ячейки типа Python и возвращает результат в виде Polars DataFrame.

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

Один из сценариев использования описан здесь.

Параметры

sql: str

Текст запроса SQL для выполнения.

Посмотреть примеры

# Пример 1

Создадим таблицу с именем из переменной table_name и запишем в нее в цикле:

  • индекс (начиная с 1)

  • слово из фразы, заданной в переменной test_phrase

  • результат применения к этому слову заданной функции length_in_chars

В каждой итерации цикла будем выводить значение индекса, добавленное слово и результат запроса SQL с текущим количеством строк в создаваемой таблице.

import tngri

def length_in_chars(text):
    if len(text) == 1:
        return '1 character'
    else:
        return f'{len(text)} characters'

table_name = 'my_table'
test_phrase = 'I love Tengri'

tngri.sql(f'CREATE OR REPLACE TABLE {table_name} \
          (index INT, word VARCHAR, length VARCHAR)'
         )

ind = 0
for word in test_phrase.split(' '):
    ind += 1
    print(f'Step: {ind}')
    tngri.sql(f"INSERT INTO {table_name} VALUES \
              ({ind}, '{word}', '{length_in_chars(word)}')"
             )
    print(f'Added word: "{word}"')
    print(tngri.sql(f'SELECT count(*) FROM {table_name}'))

print(f"Result table:\n{tngri.sql(f'SELECT * FROM {table_name} ORDER BY index')}")
Step: 1
Added word: "I"
shape: (1, 1)
┌───────┐
│ count │
│ ---   │
│ i64   │
╞═══════╡
│ 1     │
└───────┘
Step: 2
Added word: "love"
shape: (1, 1)
┌───────┐
│ count │
│ ---   │
│ i64   │
╞═══════╡
│ 2     │
└───────┘
Step: 3
Added word: "Tengri"
shape: (1, 1)
┌───────┐
│ count │
│ ---   │
│ i64   │
╞═══════╡
│ 3     │
└───────┘
Result table:
shape: (3, 3)
┌───────┬────────┬──────────────┐
│ index ┆ word   ┆ length       │
│ ---   ┆ ---    ┆ ---          │
│ i64   ┆ str    ┆ str          │
╞═══════╪════════╪══════════════╡
│ 1     ┆ I      ┆ 1 character  │
│ 2     ┆ love   ┆ 4 characters │
│ 3     ┆ Tengri ┆ 6 characters │
└───────┴────────┴──────────────┘

Теперь в ячейке типа SQL выведем созданную таблицу, упорядочив ее по индексу:

SELECT * FROM my_table
    ORDER BY index
+-------+--------+--------------+
| index | word   | length       |
+-------+--------+--------------+
| 1     | I      | 1 character  |
+-------+--------+--------------+
| 2     | love   | 4 characters |
+-------+--------+--------------+
| 3     | Tengri | 6 characters |
+-------+--------+--------------+

# Пример 2

Обратимся к выводу функции (объекту Polars DataFrame) через координаты ячейки:

print(tngri.sql('SELECT 2*2')[0,0])
4

# Пример 3

Выполним итеративную загрузку данных из файлов .parquet из хранилища S3 в таблицу по маске путей к файлам.

В каждой итерации цикла будем выводить результат запроса с количеством строк в создаваемой таблице.

import tngri

for i in range(1,4):
    file_name = f"s3://prostore/Stage/<lake_path>/{i}.parquet"
    tngri.sql(f"INSERT INTO raw_dyntest SELECT * FROM read_parquet('{file_name}')")
    print(tngri.sql("SELECT count(*) FROM raw_dyntest"))
shape: (1, 1)
+----------+
│ column_0 │
│ ---      │
│ i64      │
+----------+
│ 10000000 │
+----------+
shape: (1, 1)
+----------+
│ column_0 │
│ ---      │
│ i64      │
+----------+
│ 20000000 │
+----------+
shape: (1, 1)
+----------+
│ column_0 │
│ ---      │
│ i64      │
+----------+
│ 30000000 │
+----------+

tngri.upload_df()

Описание

Загружает данные из DataFrame в Tengri.
Использование

tngri.upload_df(df: pandas.DataFrame | polars.DataFrame, filename: str | None=None)

Загружает данные из указанного DataFrame в Tengri (в хранилище S3).
Возвращает строку с путем и именем файла .parquet, в который были загружены данные.

При необходимости для загружаемого файла можно задать имя (или путь и имя) через опциональный параметр filename.

Подробнее загрузка данных в Tengri с помощью Python описана здесь.

Параметры

df: pandas.DataFrame | polars.DataFrame

DataFrame с данными для загрузки.

filename: str | None, default None

Путь и имя файла .parquet, куда будут загружены данные. Если не указано, то будет назначено случайное имя.

Посмотреть примеры

# Пример 1

Создадим DataFrame и загрузим его в Tengri:

import tngri
import pandas

my_df = pandas.DataFrame(range(100))

tngri.upload_df(my_df)
UploadedFile(s3_path='s3://prostore/Stage/ijwsajclddxw.parquet', _client=None)

# Пример 2

Создадим DataFrame и загрузим его в Tengri по заданному пути и имени файла:

import tngri
import pandas

my_df = pandas.DataFrame(range(100))

tngri.upload_df(my_df, filename='test/my_file.parquet')
UploadedFile(s3_path='s3://prostore/Stage/test/my_file.parquet', _client=None)

# Пример 3

Создадим DataFrame, загрузим его в Tengri и запишем имя файла .parquet в переменную file_name:

import tngri
import pandas

my_df = pandas.DataFrame(range(100))
file_name = tngri.upload_df(my_df)

print(my_df)
print(file_name)
0
0    0
1    1
2    2
3    3
4    4
..  ..
95  95
96  96
97  97
98  98
99  99

[100 rows x 1 columns]
s3://prostore/Stage/tcewxknvcadf.parquet

# Пример 4

Создадим DataFrame и вставим его в существующую таблицу. В отдельную колонку запишем время вставки. После этого удалим файл .parquet.

import tngri
import pandas

df = pandas.DataFrame({"id": [1,2], "name": ['smith','brown']})

res = tngri.upload_df(df, filename=f"test_data/file.parquet")

tngri.sql(f"""
    insert into raw.test_data
    select now(), * from read_parquet('{res.s3_path}')
""")

tngri.delete_file(res)
done at 2026-04-20 14:42:07.601155

Выведем содержимое обновленной таблицы:

SELECT * FROM raw.test_data
    ORDER BY upload_time
+----------------------------+----+-------+
| upload_time                | id |  name |
+----------------------------+----+-------+
| 2026-04-20T14:42:00.707294 | 0  | alex  |
+----------------------------+----+-------+
| 2026-04-20T14:42:06.812879 | 1  | smith |
+----------------------------+----+-------+
| 2026-04-20T14:42:06.812879 | 2  | brown |
+----------------------------+----+-------+

tngri.upload_file()

Описание

Загружает данные из файла в Tengri.
Использование

tngri.upload_file(file: str, filename: str | None=None)

Загружает данные из файла по указанному пути в Tengri (в хранилище S3).
Возвращает строку с путем и именем файла внутри хранилища S3, в который были загружены данные.

Один из сценариев использования описан здесь.

Параметры

file: str

Путь к файлу, который нужно загрузить в Tengri.

filename: str | None, default None

Путь и имя файла в Tengri, куда будут загружены данные. Если не указано, то будет назначено случайное имя.

Посмотреть примеры

# Пример 1

Загрузим в Tengri данные из файла .json, доступного по URL:

import tngri
import urllib.request

urllib.request.urlretrieve(
    'https://tngri.postgrespro.ru/documentation/ru/stable/_attachments/tengri_data_types.json',
    'my_file.json'
    )

tngri.upload_file('my_file.json')
UploadedFile(s3_path='s3://prostore/Stage/pxfihzbonctd.json', _client=None)

Выведем первые 5 строк таблицы, прочитав ее из загруженного файла:

SELECT * FROM read_json('pxfihzbonctd.json')
    LIMIT 5
+----------+-----------+----------+---------------------------+
| name     | type      | category | description               |
+----------+-----------+----------+---------------------------+
| BIGINT   | data type | numeric  | Целые числа.              |
+----------+-----------+----------+---------------------------+
| BIGINT[] | data type | array    | Массивы целых чисел.      |
+----------+-----------+----------+---------------------------+
| BLOB     | data type | blob     | Двоичные объекты.         |
+----------+-----------+----------+---------------------------+
| BOOL     | data type | boolean  | Булевы значения.          |
+----------+-----------+----------+---------------------------+
| BOOL[]   | data type | array    | Массивы булевых значений. |
+----------+-----------+----------+---------------------------+

# Пример 2

Загрузим в Tengri данные из файла .json, доступного по URL, и сохраним имя загруженного файла в переменную:

import tngri
import urllib.request

urllib.request.urlretrieve(
    'https://tngri.postgrespro.ru/documentation/ru/stable/_attachments/tengri_data_types.json',
    'my_file.json'
    )

file_name = tngri.upload_file('my_file.json')
print(file_name)
s3://prostore/Stage/cytkcifdbszn.json

Выведем первые 5 строк таблицы, прочитав ее из загруженного файла:

SELECT * FROM read_json('cytkcifdbszn.json')
    LIMIT 5
+----------+-----------+----------+---------------------------+
| name     | type      | category | description               |
+----------+-----------+----------+---------------------------+
| BIGINT   | data type | numeric  | Целые числа.              |
+----------+-----------+----------+---------------------------+
| BIGINT[] | data type | array    | Массивы целых чисел.      |
+----------+-----------+----------+---------------------------+
| BLOB     | data type | blob     | Двоичные объекты.         |
+----------+-----------+----------+---------------------------+
| BOOL     | data type | boolean  | Булевы значения.          |
+----------+-----------+----------+---------------------------+
| BOOL[]   | data type | array    | Массивы булевых значений. |
+----------+-----------+----------+---------------------------+

# Пример 3

Создадим локальный файл .json, загрузим его в Tengri и вставим его содержимое в существующую таблицу. В отдельную колонку запишем время вставки. После этого удалим файл из Tengri.

Для чтения из файла .json в формате списка используем функцию read_json_objects с параметром format='array'.

import tngri

localpath = 'file.json'

with open(localpath, 'w') as file:
    file.write('[{"id": 123, "name": "smith"}, {"id": 124, "name": "brown"}]')

res = tngri.upload_file(localpath, filename=f"test_data/file.json")

tngri.sql(f"""
    insert into raw.test_data
    select now(), * from read_json_objects('{res.s3_path}', format='array')
""")

tngri.delete_file(res)
done at 2026-02-11 16:34:22.378942

Выведем содержимое обновленной таблицы:

SELECT * FROM raw.test_data
+----------------------------+------------------------------+
| upload_time                | body                         |
+----------------------------+------------------------------+
| 2026-04-20T16:34:21.875707 | {"id": 123, "name": "smith"} |
+----------------------------+------------------------------+
| 2026-04-20T16:34:21.875707 | {"id": 124, "name": "brown"} |
+----------------------------+------------------------------+
| 2026-04-20T16:30:22.865707 | {"id": 122, "name": "alex"}  |
+----------------------------+------------------------------+

tngri.upload_s3()

Описание

Загружает файл из указанного бакета S3 в Tengri.
Использование

tngri.upload_s3(object: str, access_key: str, secret_key: str, *, filename: str | None=None)

Загружает файл из указанного бакета S3 в Tengri. Расширение файла при этом может быть любым. Оно останется тем же, каким оно было в исходном файле.

Параметры

object: str

Путь к файлу в хранилище S3.

access_key: str

Ключ доступа для S3.

secret_key: str

Секретный ключ для S3.

filename: str | None, default None

Путь и имя файла в Tengri, куда будут загружены данные. Если не указано, то будет назначено случайное имя.

Пример использования описан здесь.