diff --git a/doc/how-to/getting_started_net_box.rst b/doc/how-to/getting_started_net_box.rst new file mode 100644 index 0000000000..154892bce4 --- /dev/null +++ b/doc/how-to/getting_started_net_box.rst @@ -0,0 +1,153 @@ +.. _getting_started_net_box: + +Getting started with net.box +============================ + +The tutorial shows how to work with some common ``net.box`` methods. + +For more information about the ``net.box`` module, +check the :ref:`corresponding module reference `. + +Sandbox configuration +--------------------- + +The sandbox configuration for the tutorial assumes that: + +* The Tarantool instance is running on ``localhost 127.0.0.1:3301``. +* There is a space named ``tester`` with a numeric primary key. +* The space contains a tuple with the key value = ``800``. +* The current user has read, write, and execute privileges. + +Use the commands below for a quick sandbox setup: + +.. code-block:: lua + + box.cfg{listen = 3301} + s = box.schema.space.create('tester') + s:create_index('primary', {type = 'hash', parts = {1, 'unsigned'}}) + t = s:insert({800, 'TEST'}) + box.schema.user.grant('guest', 'read,write,execute', 'universe') + +Creating a net.box connection +----------------------------- + +First, load the ``net.box`` module with the ``require('net.box')`` method: + +.. code-block:: tarantoolsession + + tarantool> net_box = require('net.box') + +The next step is to create a new connection. +In ``net.box``, self-connection is pre-established. +That is, ``conn = net_box.connect('localhost:3301')`` command can be replaced with the ``conn = net_box.self`` object call: + +.. code-block:: tarantoolsession + + tarantool> conn = net_box.self + +Then, make a ping: + +.. code-block:: tarantoolsession + + tarantool> conn:ping() + --- + - true + ... + +Using data operations +--------------------- + +Select all tuples in the ``tester`` space where the key value is ``800``: + +.. code-block:: tarantoolsession + + tarantool> conn.space.tester:select{800} + --- + - - [800, 'TEST'] + ... + +Insert two tuples into the space: + +.. code-block:: tarantoolsession + + tarantool> conn.space.tester:insert({700, 'TEST700'}) + --- + - [700, 'TEST700'] + ... + tarantool> conn.space.tester:insert({600, 'TEST600'}) + --- + - [600, 'TEST600'] + ... + +After the insert, there is one tuple where the key value is ``600``. +To select this tuple, you can use the ``get()`` method. +Unlike the ``select()`` command, ``get()`` returns only one tuple that satisfies the stated condition. + +.. code-block:: tarantoolsession + + tarantool> conn.space.tester:get({600}) + --- + - [600, 'TEST600'] + ... + +To update the existing tuple, you can use either ``update()`` or ``upsert()``. +The ``update()`` method can be used for assignment, arithmetic (if the field is numeric), +cutting and pasting fragments of a field, and deleting or inserting a field. + +In this tutorial, the ``update()`` command is used to update the tuple identified by primary key value = ``800``. +The operation assigns a new value to the second field in the tuple: + +.. code-block:: tarantoolsession + + tarantool> conn.space.tester:update(800, {{'=', 2, 'TEST800'}}) + --- + - [800, 'TEST800'] + ... + +As for the ``upsert`` function, if there is an existing tuple that matches the key field of tuple, then the command +has the same effect as ``update()``. +Otherwise, the effect is equal to the ``insert()`` method. + +.. code-block:: tarantoolsession + + tarantool> conn.space.tester:upsert({500, 'TEST500'}, {{'=', 2, 'TEST'}}) + +To delete a tuple where the key value is ``600``, run the ``delete()`` method below: + +.. code-block:: tarantoolsession + + tarantool> conn.space.tester:delete{600} + --- + - [600, 'TEST600'] + ... + +Then, replace the existing tuple with a new one: + +.. code-block:: tarantoolsession + + tarantool> conn.space.tester:replace{500, 'New data', 'Extra data'} + --- + - [500, 'New data', 'Extra data'] + ... + +Finally, select all tuples from the space: + +.. code-block:: tarantoolsession + + tarantool> conn.space.tester:select{} + --- + - - [800, 'TEST800'] + - [500, 'New data', 'Extra data'] + - [700, 'TEST700'] + ... + +Closing the connection +---------------------- + +In the end, close the connection when it is no longer needed: + +.. code-block:: tarantoolsession + + tarantool> conn:close() + --- + ... \ No newline at end of file diff --git a/doc/how-to/index.rst b/doc/how-to/index.rst index 88f3459434..546db4f367 100644 --- a/doc/how-to/index.rst +++ b/doc/how-to/index.rst @@ -20,6 +20,7 @@ If you are new to Tarantool, please see our getting_started_connectors getting_started_cartridge db/index + getting_started_net_box vshard_quick app/index replication/index diff --git a/doc/reference/reference_lua/net_box.rst b/doc/reference/reference_lua/net_box.rst index e4c4792555..51d430f78d 100644 --- a/doc/reference/reference_lua/net_box.rst +++ b/doc/reference/reference_lua/net_box.rst @@ -13,6 +13,7 @@ variant, to be discussed later, is for connecting to MySQL or MariaDB or Postgre (see :ref:`SQL DBMS modules ` reference). The other variant, which is discussed in this section, is for connecting to Tarantool server instances via a network. +For a quick start with ``net.box``, refer to the :ref:`tutorial `. You can call the following methods: @@ -884,89 +885,4 @@ With the ``net.box`` module, you can use the following existing trigger functions. Details about trigger characteristics are in the - :ref:`triggers ` section. - -============================================================================ -Example -============================================================================ - -This example shows the use of most of the ``net.box`` methods. - -The sandbox configuration for this example assumes that: - -* the Tarantool instance is running on ``localhost 127.0.0.1:3301``, -* there is a space named ``tester`` with a numeric primary key and with a tuple - that contains a key value = 800, -* the current user has read, write and execute privileges. - -Here are commands for a quick sandbox setup: - -.. code-block:: lua - - box.cfg{listen = 3301} - s = box.schema.space.create('tester') - s:create_index('primary', {type = 'hash', parts = {1, 'unsigned'}}) - t = s:insert({800, 'TEST'}) - box.schema.user.grant('guest', 'read,write,execute', 'universe') - -And here starts the example: - -.. code-block:: tarantoolsession - - tarantool> net_box = require('net.box') - --- - ... - tarantool> function example() - > local conn, wtuple - > if net_box.self:ping() then - > table.insert(ta, 'self:ping() succeeded') - > table.insert(ta, ' (no surprise -- self connection is pre-established)') - > end - > if box.cfg.listen == '3301' then - > table.insert(ta,'The local server listen address = 3301') - > else - > table.insert(ta, 'The local server listen address is not 3301') - > table.insert(ta, '( (maybe box.cfg{...listen="3301"...} was not stated)') - > table.insert(ta, '( (so connect will fail)') - > end - > conn = net_box.connect('127.0.0.1:3301') - > conn.space.tester:delete({800}) - > table.insert(ta, 'conn delete done on tester.') - > conn.space.tester:insert({800, 'data'}) - > table.insert(ta, 'conn insert done on tester, index 0') - > table.insert(ta, ' primary key value = 800.') - > wtuple = conn.space.tester:select({800}) - > table.insert(ta, 'conn select done on tester, index 0') - > table.insert(ta, ' number of fields = ' .. #wtuple) - > conn.space.tester:delete({800}) - > table.insert(ta, 'conn delete done on tester') - > conn.space.tester:replace({800, 'New data', 'Extra data'}) - > table.insert(ta, 'conn:replace done on tester') - > conn.space.tester:update({800}, {{'=', 2, 'Fld#1'}}) - > table.insert(ta, 'conn update done on tester') - > conn:close() - > table.insert(ta, 'conn close done') - > end - --- - ... - tarantool> ta = {} - --- - ... - tarantool> example() - --- - ... - tarantool> ta - --- - - - self:ping() succeeded - - ' (no surprise -- self connection is pre-established)' - - The local server listen address = 3301 - - conn delete done on tester. - - conn insert done on tester, index 0 - - ' primary key value = 800.' - - conn select done on tester, index 0 - - ' number of fields = 1' - - conn delete done on tester - - conn:replace done on tester - - conn update done on tester - - conn close done - ... + :ref:`triggers ` section. \ No newline at end of file diff --git a/locale/ru/LC_MESSAGES/how-to/getting_started_net_box.po b/locale/ru/LC_MESSAGES/how-to/getting_started_net_box.po new file mode 100644 index 0000000000..2d551ae658 --- /dev/null +++ b/locale/ru/LC_MESSAGES/how-to/getting_started_net_box.po @@ -0,0 +1,129 @@ + +msgid "Getting started with net.box" +msgstr "Начало работы с net.box" + +msgid "The tutorial shows how to work with some common ``net.box`` methods." +msgstr "Ниже приводится пример использования большинства методов ``net.box``." + +msgid "" +"For more information about the ``net.box`` module, " +"check the :ref:`corresponding module reference `." +msgstr "" +"Подробную информацию о модуле ``net.box`` вы найдете " +"в соответствующем :ref:`разделе справочника по модулям `." + +msgid "Sandbox configuration" +msgstr "Настройка песочницы" + +msgid "The sandbox configuration for the tutorial assumes that:" +msgstr "" +"Данный пример сработает на конфигурации из песочницы, предполагается, что:" + +msgid "The Tarantool instance is running on ``localhost 127.0.0.1:3301``." +msgstr "экземпляр Tarantool запущен на ``localhost 127.0.0.1:3301``;" + +msgid "There is a space named ``tester`` with a numeric primary key." +msgstr "создан спейс под названием ``tester`` с первичным числовым ключом;" + +msgid "The space contains a tuple with the key value = ``800``." +msgstr "спейс содержит кортеж, в котором есть ключ со значением = 800;" + +msgid "The current user has read, write, and execute privileges." +msgstr "у текущего пользователя есть права на чтение, запись и выполнение." + +msgid "Use the commands below for a quick sandbox setup:" +msgstr "Используйте команды ниже для быстрой настройки песочницы:" + +msgid "Creating a net.box connection" +msgstr "Создание подключения" + +msgid "" +"First, load the ``net.box`` module with " +"the ``require('net.box')`` method:" +msgstr "" +"Чтобы начать работу, запустите модуль ``net.box``, " +"используя команду ``require('net.box')``:" + +msgid "" +"The next step is to create a new connection. " +"In ``net.box``, self-connection is pre-established. That is, " +"``conn = net_box.connect('localhost:3301')`` command can be " +"replaced with the ``conn = net_box.self`` object call:" +msgstr "" +"Далее необходимо создать новое подключение. " +"В ``net.box`` для локального Tarantool-сервера есть заданный объект ``self`` всегда " +"установленного подключения. Таким образом, команду ``conn = net_box.connect('localhost:3301')`` " +"можно заменить на вызов объекта ``conn = net_box.self``." + +msgid "Then, make a ping:" +msgstr "Запустите команду ``ping()``:" + +msgid "Using data operations" +msgstr "Операции с данными" + +msgid "Select all tuples in the ``tester`` space where the key value is ``800``:" +msgstr "Сделайте выборку всех кортежей в спейсе ``tester``, у которых значение ключа равно ``800``:" + +msgid "Insert two tuples into the space:" +msgstr "Вставьте два кортежа в спейс:" + +msgid "" +"After the insert, there is one tuple where the key value is ``600``. " +"To select this tuple, you can use the ``get()`` method. " +"Unlike the ``select()`` command, ``get()`` returns only one tuple " +"that satisfies the stated condition." +msgstr "" +"После вставки в спейсе появился один кортеж со значением ключа ``600``. " +"Для выбора этого кортежа вы можете использовать метод ``get()``. " +"В отличие от команды ``select()``, метод ``get()`` возвращает только один кортеж, " +"удовлетворяющий заданным условиям." + +msgid "" +"To update the existing tuple, you can use either ``update()`` or ``upsert()``. " +"The ``update()`` method can be used for assignment, " +"arithmetic (if the field is numeric), " +"cutting and pasting fragments of a field, and deleting or inserting a field." +msgstr "" +"Чтобы обновить существующий кортеж, вы можете использовать как метод ``update()``, так и метод ``upsert()``. " +"Функция ``update()`` может использоваться для присваивания, " +"арифметических операций (если поле числовое), вырезания и вставки фрагментов" +" поля, а также для удаления или вставки поля." + +msgid "" +"In this tutorial, the ``update()`` command is used to update the tuple " +"identified by primary key value = ``800``. " +"The operation assigns a new value to the second field in the tuple:" +msgstr "" +"В этом руководстве команда ``update()`` используется для обновления кортежа, " +"определенного значением ключа ``800``. " +"Операция присваивает новое значение второму полю в кортеже:" + +msgid "" +"As for the ``upsert`` function, if there is an existing tuple " +"that matches the key field of tuple, then the command " +"has the same effect as ``update()``. " +"Otherwise, the effect is equal to the ``insert()`` method." +msgstr "" +"Для функции ``upsert``, если уже существует кортеж, " +"который совпадает с ключевыми полями tuple, запрос приведет к тому же " +"результату, что и метод ``update()``. Если подходящего кортежа нет," +" запрос приведет к тому же результату, что и метод ``insert()``." + +msgid "" +"To delete a tuple where the key value is ``600``, " +"run the ``delete()`` method below:" +msgstr "" +"Чтобы удалить кортеж, в котором значение ключа равно ``600``, " +"запустите метод ``delete()``:" + +msgid "Then, replace the existing tuple with a new one:" +msgstr "Затем замените существующий кортеж на новый:" + +msgid "Finally, select all tuples from the space:" +msgstr "Наконец, сделайте выборку по всем кортежам из спейса:" + +msgid "Closing the connection" +msgstr "Закрытие подключения" + +msgid "In the end, close the connection when it is no longer needed:" +msgstr "Закройте соединение явным образом, когда оно больше не используется:" diff --git a/locale/ru/LC_MESSAGES/reference/reference_lua/net_box.po b/locale/ru/LC_MESSAGES/reference/reference_lua/net_box.po index 965f463575..4f3b3ff04e 100644 --- a/locale/ru/LC_MESSAGES/reference/reference_lua/net_box.po +++ b/locale/ru/LC_MESSAGES/reference/reference_lua/net_box.po @@ -10,14 +10,16 @@ msgid "" "variant, to be discussed later, is for connecting to MySQL or MariaDB or " "PostgreSQL (see :ref:`SQL DBMS modules ` reference). The other" " variant, which is discussed in this section, is for connecting to Tarantool" -" server instances via a network." +" server instances via a network. For a quick start with ``net.box``, " +"refer to the :ref:`tutorial `." msgstr "" "Модуль ``net.box`` включает в себя коннекторы для удаленных систем с базами " "данных. Одним из вариантов, который рассматривается позднее, является " "подключение к MySQL, MariaDB или PostgreSQL (см. справочник по :ref:`Модулям" " СУБД SQL `). Другим вариантом, который рассматривается в " "данном разделе, является подключение к экземплярам Tarantool-сервера по " -"сети." +"сети. Для быстрого знакомства с ``net.box`` вы можете обратиться к разделу" +" :ref:`Начало работы с net.box `." msgid "You can call the following methods:" msgstr "Можно вызвать следующие методы:" @@ -1053,163 +1055,4 @@ msgid "" "box_triggers>` section." msgstr "" "Подробная информация о характеристиках триггера находится в разделе " -":ref:`Триггеры `." - -msgid "Example" -msgstr "Пример" - -msgid "This example shows the use of most of the ``net.box`` methods." -msgstr "Ниже приводится пример использования большинства методов ``net.box``." - -msgid "The sandbox configuration for this example assumes that:" -msgstr "" -"Данный пример сработает на конфигурации из песочницы, предполагается, что:" - -msgid "the Tarantool instance is running on ``localhost 127.0.0.1:3301``," -msgstr "экземпляр Tarantool запущен на ``localhost 127.0.0.1:3301``," - -msgid "" -"there is a space named ``tester`` with a numeric primary key and with a " -"tuple that contains a key value = 800," -msgstr "" -"создан спейс под названием ``tester`` с первичным числовым ключом и " -"кортежем, в котором есть ключ со значением= 800," - -msgid "the current user has read, write and execute privileges." -msgstr "у текущего пользователя есть права на чтение, запись и выполнение." - -msgid "Here are commands for a quick sandbox setup:" -msgstr "Ниже приведены команды для быстрой настройки песочницы:" - -msgid "" -"box.cfg{listen = 3301}\n" -"s = box.schema.space.create('tester')\n" -"s:create_index('primary', {type = 'hash', parts = {1, 'unsigned'}})\n" -"t = s:insert({800, 'TEST'})\n" -"box.schema.user.grant('guest', 'read,write,execute', 'universe')" -msgstr "" -"box.cfg{listen = 3301}\n" -"s = box.schema.space.create('tester')\n" -"s:create_index('primary', {type = 'hash', parts = {1, 'unsigned'}})\n" -"t = s:insert({800, 'TEST'})\n" -"box.schema.user.grant('guest', 'read,write,execute', 'universe')" - -msgid "And here starts the example:" -msgstr "А здесь приведен пример:" - -msgid "" -"tarantool> net_box = require('net.box')\n" -"---\n" -"...\n" -"tarantool> function example()\n" -" > local conn, wtuple\n" -" > if net_box.self:ping() then\n" -" > table.insert(ta, 'self:ping() succeeded')\n" -" > table.insert(ta, ' (no surprise -- self connection is pre-established)')\n" -" > end\n" -" > if box.cfg.listen == '3301' then\n" -" > table.insert(ta,'The local server listen address = 3301')\n" -" > else\n" -" > table.insert(ta, 'The local server listen address is not 3301')\n" -" > table.insert(ta, '( (maybe box.cfg{...listen=\"3301\"...} was not stated)')\n" -" > table.insert(ta, '( (so connect will fail)')\n" -" > end\n" -" > conn = net_box.connect('127.0.0.1:3301')\n" -" > conn.space.tester:delete({800})\n" -" > table.insert(ta, 'conn delete done on tester.')\n" -" > conn.space.tester:insert({800, 'data'})\n" -" > table.insert(ta, 'conn insert done on tester, index 0')\n" -" > table.insert(ta, ' primary key value = 800.')\n" -" > wtuple = conn.space.tester:select({800})\n" -" > table.insert(ta, 'conn select done on tester, index 0')\n" -" > table.insert(ta, ' number of fields = ' .. #wtuple)\n" -" > conn.space.tester:delete({800})\n" -" > table.insert(ta, 'conn delete done on tester')\n" -" > conn.space.tester:replace({800, 'New data', 'Extra data'})\n" -" > table.insert(ta, 'conn:replace done on tester')\n" -" > conn.space.tester:update({800}, {{'=', 2, 'Fld#1'}})\n" -" > table.insert(ta, 'conn update done on tester')\n" -" > conn:close()\n" -" > table.insert(ta, 'conn close done')\n" -" > end\n" -"---\n" -"...\n" -"tarantool> ta = {}\n" -"---\n" -"...\n" -"tarantool> example()\n" -"---\n" -"...\n" -"tarantool> ta\n" -"---\n" -"- - self:ping() succeeded\n" -" - ' (no surprise -- self connection is pre-established)'\n" -" - The local server listen address = 3301\n" -" - conn delete done on tester.\n" -" - conn insert done on tester, index 0\n" -" - ' primary key value = 800.'\n" -" - conn select done on tester, index 0\n" -" - ' number of fields = 1'\n" -" - conn delete done on tester\n" -" - conn:replace done on tester\n" -" - conn update done on tester\n" -" - conn close done\n" -"..." -msgstr "" -"tarantool> net_box = require('net.box')\n" -"---\n" -"...\n" -"tarantool> function example()\n" -" > local conn, wtuple\n" -" > if net_box.self:ping() then\n" -" > table.insert(ta, 'self:ping() succeeded')\n" -" > table.insert(ta, ' (no surprise -- self connection is pre-established)')\n" -" > end\n" -" > if box.cfg.listen == '3301' then\n" -" > table.insert(ta,'The local server listen address = 3301')\n" -" > else\n" -" > table.insert(ta, 'The local server listen address is not 3301')\n" -" > table.insert(ta, '( (maybe box.cfg{...listen=\"3301\"...} was not stated)')\n" -" > table.insert(ta, '( (so connect will fail)')\n" -" > end\n" -" > conn = net_box.connect('127.0.0.1:3301')\n" -" > conn.space.tester:delete({800})\n" -" > table.insert(ta, 'conn delete done on tester.')\n" -" > conn.space.tester:insert({800, 'data'})\n" -" > table.insert(ta, 'conn insert done on tester, index 0')\n" -" > table.insert(ta, ' primary key value = 800.')\n" -" > wtuple = conn.space.tester:select({800})\n" -" > table.insert(ta, 'conn select done on tester, index 0')\n" -" > table.insert(ta, ' number of fields = ' .. #wtuple)\n" -" > conn.space.tester:delete({800})\n" -" > table.insert(ta, 'conn delete done on tester')\n" -" > conn.space.tester:replace({800, 'New data', 'Extra data'})\n" -" > table.insert(ta, 'conn:replace done on tester')\n" -" > conn.space.tester:update({800}, {{'=', 2, 'Fld#1'}})\n" -" > table.insert(ta, 'conn update done on tester')\n" -" > conn:close()\n" -" > table.insert(ta, 'conn close done')\n" -" > end\n" -"---\n" -"...\n" -"tarantool> ta = {}\n" -"---\n" -"...\n" -"tarantool> example()\n" -"---\n" -"...\n" -"tarantool> ta\n" -"---\n" -"- - self:ping() succeeded\n" -" - ' (no surprise -- self connection is pre-established)'\n" -" - The local server listen address = 3301\n" -" - conn delete done on tester.\n" -" - conn insert done on tester, index 0\n" -" - ' primary key value = 800.'\n" -" - conn select done on tester, index 0\n" -" - ' number of fields = 1'\n" -" - conn delete done on tester\n" -" - conn:replace done on tester\n" -" - conn update done on tester\n" -" - conn close done\n" -"..." +":ref:`Триггеры `." \ No newline at end of file