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

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

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

`tngri.create_table()`

Описание	Создает таблицу и наполняет ее данными из DataFrame.
Использование	`tngri.create_table(DataFrame, '<table_name>')`

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

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

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

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

import tngri
import pandas as pd

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

tngri.create_table(df, 'demo.capitals')

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(Path)`

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

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

Пройдем по всем файлам в директории 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(Path)`

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

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

Имя и путь к файлу
Размер файла
Время последнего изменения

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

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

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_name>')`

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

ok: bool — Был ли запуск успешным
output: str — Результаты вывода всех ячеек типа Python
errors: str — Текст ошибок

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

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

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

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

import tngri

result = tngri.run_notebook('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_query>')`

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

Функцией удобно пользоваться при необходимости выполнить какие-либо запросы SQL непосредственно внутри ячейки типа Python, например, внутри цикла или в других сложных конструкциях, не создавая для этого отдельную ячейку типа SQL и используя любые локальные переменные и функции Python внутри текста запроса 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])

Пример 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(DataFrame [, filename = '<FileName>'])`

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

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

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

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

Создадим 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)

Создадим 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)

Создадим 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

`tngri.upload_file()`

Описание	Загружает данные из файла в Tengri.
Использование	`tngri.upload_file(FilePath[, filename = '<FileName>'])`

FilePath — путь к файлу, который нужно загрузить в Tengri
FileName — имя (или путь и имя) для файла в Tengri

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

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

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

Загрузим в 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    | Массивы булевых значений. |
+----------+-----------+----------+---------------------------+

Загрузим в 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    | Массивы булевых значений. |
+----------+-----------+----------+---------------------------+

`tngri.upload_s3()`

Описание	Загружает файл из указанного бакета S3 в Tengri.
Использование	`tngri.upload_s3( object = 's3://<file_path>.parquet', access_key = '<access_key>', secret_key = '<secret_key>'[, filename = '<FileName>'] )`

object — путь к файлу в хранилище S3.
access_key — ключ доступа для S3.
secret_key — секретный ключ для S3.

Расширение файла при этом может быть любым. Оно останется тем же, каким оно было в начальном файле.

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

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

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

tngri.create_table()

tngri.delete_file()

tngri.list_files()

tngri.run_notebook()

tngri.sql()

Пример 1

Пример 2

Пример 3

tngri.upload_df()

tngri.upload_file()

tngri.upload_s3()

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

`tngri.create_table()`

`tngri.delete_file()`

`tngri.list_files()`

`tngri.run_notebook()`

`tngri.sql()`

`tngri.upload_df()`

`tngri.upload_file()`

`tngri.upload_s3()`