Skip to content

Commit 91a14ab

Browse files
vgvolegvgvoleg
committed
Update examples
1 parent 5f37bd0 commit 91a14ab

File tree

2 files changed

+147
-57
lines changed

2 files changed

+147
-57
lines changed

‎docs/examples.rst

Lines changed: 145 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,155 @@
11
Examples
22
===============
33

4-
ydb
5-
^^^
4+
Basic example
5+
^^^^^^^^^^^^^
6+
7+
All examples in this section are parts of `basic example <https://github.com/ydb-platform/ydb-python-sdk/tree/main/examples/basic_example_v2>`_.
8+
9+
For deeper upderstanding it is better to read the whole example.
610

711
Create table
812
------------
913

10-
::
11-
12-
... create an instance of Driver ...
13-
14-
description = (
15-
ydb.TableDescription()
16-
.with_primary_keys('key1', 'key2')
17-
.with_columns(
18-
ydb.Column('key1', ydb.OptionalType(ydb.PrimitiveType.Uint64)),
19-
ydb.Column('key2', ydb.OptionalType(ydb.PrimitiveType.Uint64)),
20-
ydb.Column('value', ydb.OptionalType(ydb.PrimitiveType.Utf8))
21-
)
22-
.with_profile(
23-
ydb.TableProfile()
24-
.with_partitioning_policy(
25-
ydb.PartitioningPolicy()
26-
.with_explicit_partitions(
27-
ydb.ExplicitPartitions(
28-
(
29-
ydb.KeyBound((100, )),
30-
ydb.KeyBound((300, 100)),
31-
ydb.KeyBound((400, )),
32-
)
33-
)
34-
)
35-
)
36-
)
37-
)
38-
39-
session = driver.table_client.session().create()
40-
session.create_table('/my/table/', description)
41-
42-
43-
Read table
14+
.. code-block:: python
15+
16+
def create_tables(pool: ydb.QuerySessionPool):
17+
print("\nCreating table series...")
18+
pool.execute_with_retries(
19+
"""
20+
CREATE table `series` (
21+
`series_id` Int64,
22+
`title` Utf8,
23+
`series_info` Utf8,
24+
`release_date` Date,
25+
PRIMARY KEY (`series_id`)
26+
)
27+
"""
28+
)
29+
30+
print("\nCreating table seasons...")
31+
pool.execute_with_retries(
32+
"""
33+
CREATE table `seasons` (
34+
`series_id` Int64,
35+
`season_id` Int64,
36+
`title` Utf8,
37+
`first_aired` Date,
38+
`last_aired` Date,
39+
PRIMARY KEY (`series_id`, `season_id`)
40+
)
41+
"""
42+
)
43+
44+
print("\nCreating table episodes...")
45+
pool.execute_with_retries(
46+
"""
47+
CREATE table `episodes` (
48+
`series_id` Int64,
49+
`season_id` Int64,
50+
`episode_id` Int64,
51+
`title` Utf8,
52+
`air_date` Date,
53+
PRIMARY KEY (`series_id`, `season_id`, `episode_id`)
54+
)
55+
"""
56+
)
57+
58+
59+
Upsert Simple
60+
-------------
61+
62+
.. code-block:: python
63+
64+
def upsert_simple(pool: ydb.QuerySessionPool):
65+
print("\nPerforming UPSERT into episodes...")
66+
67+
pool.execute_with_retries(
68+
"""
69+
UPSERT INTO episodes (series_id, season_id, episode_id, title) VALUES (2, 6, 1, "TBD");
70+
"""
71+
)
72+
73+
74+
Simple Select
4475
----------
45-
::
46-
47-
.... initialize driver and session ....
48-
49-
key_prefix_type = ydb.TupleType().add_element(
50-
ydb.OptionalType(ydb.PrimitiveType.Uint64).add_element(
51-
ydb.OptionalType(ydb.PrimitiveType.Utf8))
52-
async_table_iterator = session.read_table(
53-
'/my/table',
54-
columns=('KeyColumn0', 'KeyColumn1', 'ValueColumn'),
55-
ydb.KeyRange(
56-
ydb.KeyBound((100, 'hundred'), key_prefix_type)
57-
ydb.KeyBound((200, 'two-hundreds'), key_prefix_type)
58-
)
76+
77+
.. code-block:: python
78+
79+
def select_simple(pool: ydb.QuerySessionPool):
80+
print("\nCheck series table...")
81+
result_sets = pool.execute_with_retries(
82+
"""
83+
SELECT
84+
series_id,
85+
title,
86+
release_date
87+
FROM series
88+
WHERE series_id = 1;
89+
""",
90+
)
91+
first_set = result_sets[0]
92+
for row in first_set.rows:
93+
print(
94+
"series, id: ",
95+
row.series_id,
96+
", title: ",
97+
row.title,
98+
", release date: ",
99+
row.release_date,
59100
)
60101
61-
while True:
62-
try:
63-
chunk_future = next(table_iterator)
64-
chunk = chunk_future.result() # or any other way to await
65-
... additional data processing ...
66-
except StopIteration:
67-
break
102+
return first_set
103+
104+
Select With Parameters
105+
----------------------
106+
107+
.. code-block:: python
108+
109+
def select_with_parameters(pool: ydb.QuerySessionPool, series_id, season_id, episode_id):
110+
result_sets = pool.execute_with_retries(
111+
"""
112+
DECLARE $seriesId AS Int64;
113+
DECLARE $seasonId AS Int64;
114+
DECLARE $episodeId AS Int64;
115+
116+
SELECT
117+
title,
118+
air_date
119+
FROM episodes
120+
WHERE series_id = $seriesId AND season_id = $seasonId AND episode_id = $episodeId;
121+
""",
122+
{
123+
"$seriesId": series_id, # could be defined implicit
124+
"$seasonId": (season_id, ydb.PrimitiveType.Int64), # could be defined via tuple
125+
"$episodeId": ydb.TypedValue(episode_id, ydb.PrimitiveType.Int64), # could be defined via special class
126+
},
127+
)
128+
129+
print("\n> select_with_parameters:")
130+
first_set = result_sets[0]
131+
for row in first_set.rows:
132+
print("episode title:", row.title, ", air date:", row.air_date)
133+
134+
return first_set
135+
136+
Huge Select
137+
-----------
138+
139+
.. code-block:: python
140+
141+
def huge_select(pool: ydb.QuerySessionPool):
142+
def callee(session: ydb.QuerySessionSync):
143+
query = """SELECT * from episodes;"""
144+
145+
with session.transaction().execute(
146+
query,
147+
commit_tx=True,
148+
) as result_sets:
149+
print("\n> Huge SELECT call")
150+
for result_set in result_sets:
151+
for row in result_set.rows:
152+
print("episode title:", row.title, ", air date:", row.air_date)
153+
154+
return pool.retry_operation_sync(callee)
155+

‎docs/quickstart.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,12 +68,14 @@ Python SDK supports queries described by YQL syntax.
6868
There are two primary methods for executing queries, each with different properties and use cases:
6969

7070
* ``pool.execute_with_retries``:
71+
7172
* Buffers the entire result set in client memory.
7273
* Automatically retries execution in case of retriable issues.
7374
* Does not allow specifying a transaction execution mode.
7475
* Recommended for one-off queries that are expected to produce small result sets.
7576

7677
* ``tx.execute``:
78+
7779
* Returns an iterator over the query results, allowing processing of results that may not fit into client memory.
7880
* Retries must be handled manually via `pool.retry_operation_sync`.
7981
* Allows specifying a transaction execution mode.

0 commit comments

Comments
 (0)