Модуль источников данных sql
=========================================

.. py:module:: axioma.core.sql
.. currentmodule:: axioma.core.sql

В данном модуле содержатся классы и методы для выполнения локальных sql запросов

Список классов
--------------

.. toctree::
	:glob:

	sql/*


Функции выполнения SQL запросов
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	.. note:: При вызове версий функций, не имеющих среду выполнения запросов \
		:class:`~axioma.core.sql.SqlRuntime` в качестве одного из своих параметров, \
		будет произведена попытка ее получения из инициализированного ядра \
		приложения :class:`~axioma.core.Core`

	.. function:: selectAsTable(query_text, context, runtime)

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

		:param query_text: текст запроса
		:type query_text: :class:`str`
		:param context: контекст таблиц
		:type context: :class:`~axioma.core.sql.TableContext`
		:param runtime: среда выполнения запросов
		:type runtime: :class:`~axioma.core.sql.SqlRuntime`
		:return: таблица, представляющая результат запроса
		:rtype: :class:`~axioma.core.sql.QueryTable`
		:raises Runtime: :exc:`~axioma.common.RuntimeException` - Ошибка времени выполнения

	.. function:: selectAsTable(query_text, context)

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

		:param query_text: текст запроса
		:type query_text: :class:`str`
		:param context: контекст таблиц
		:type context: :class:`~axioma.core.sql.TableContext`
		:return: таблица, представляющая результат запроса
		:rtype: :class:`~axioma.core.sql.QueryTable`
		:raises Runtime: :exc:`~axioma.common.RuntimeException` - Ошибка времени выполнения

		.. code-block:: python
			:caption: Пример использования
			:name: axioma.core.sql.selectAtTable.code_sample

			# Запрос всех стран с названием 'Hungary'
			from axioma.core.sql import *

			# ...
			# table - Таблица 'world'
			# ...

			# создадим контекст
			context = SimpleTableContext(table)

			# SELECT AS TABLE
			query_text = "SELECT * FROM world WHERE country=\"Hungary\""
			select_table = selectAsTable(query_text, context)

			print("Имя таблицы выборки: %s" % select_table.name())
			print("Количество записей: %d" % len(select_table.allFeatures()))
			print("Количество атрибутов: %d" % len(select_table.attributeNames()))

			# Вывод:
			# >>> Имя таблицы выборки: Query
			# >>> Количество записей: 1
			# >>> Количество атрибутов: 32

	.. function:: select(query_text, context, runtime)

		Запрос типа "Выборка" (SELECT)

		:param query_text: текст запроса
		:type query_text: :class:`str`
		:param context: контекст таблиц
		:type context: :class:`~axioma.core.sql.TableContext`
		:param runtime: среда выполнения запросов
		:type runtime: :class:`~axioma.core.sql.SqlRuntime`
		:return: результат выполнения запроса
		:rtype: :class:`~axioma.core.sql.QueryResult`
		:raises Runtime: :exc:`~axioma.common.RuntimeException` - Ошибка времени выполнения

	.. function:: select(query_text, context)

		Запрос типа "Выборка" (SELECT)

		:param query_text: текст запроса
		:type query_text: :class:`str`
		:param context: контекст таблиц
		:type context: :class:`~axioma.core.sql.TableContext`
		:return: результат выполнения запроса
		:rtype: :class:`~axioma.core.sql.QueryResult`
		:raises Runtime: :exc:`~axioma.common.RuntimeException` - Ошибка времени выполнения

		.. code-block:: python
			:caption: Пример использования
			:name: axioma.core.sql.select.code_sample

			# Страны с населением более 100 миллионов
			from axioma.core.sql import *

			# ...
			# table - Таблица 'world'
			# ...

			# создадим контекст
			context = SimpleTableContext(table)

			# SELECT
			query_text = "SELECT Страна FROM world WHERE Население>100000000"
			select_table = selectAsTable(query_text, context)

			result = select(query_text, context)

			print([feature.getAttribute("Страна") for feature in result.features])

			# Вывод:
			# >>> ['Бангладеш', 'Бразилия', 'Китай', 'Индия', 'Индонезия',
			#      'Япония', 'Российская Федерация', 'Соединенные Штаты Америки']

	.. function:: update(query_text, context, runtime)

		Запрос типа "Изменение" (UPDATE)

		:param query_text: текст запроса
		:type query_text: :class:`str`
		:param context: контекст таблиц
		:type context: :class:`~axioma.core.sql.TableContext`
		:param runtime: среда выполнения запросов
		:type runtime: :class:`~axioma.core.sql.SqlRuntime`
		:return: количество измененных записей
		:rtype: :class:`int`
		:raises Runtime: :exc:`~axioma.common.RuntimeException` - Ошибка времени выполнения

	.. function:: update(query_text, context)

		Запрос типа "Изменение" (UPDATE)

		:param query_text: текст запроса
		:type query_text: :class:`str`
		:param context: контекст таблиц
		:type context: :class:`~axioma.core.sql.TableContext`
		:param runtime: среда выполнения запросов
		:type runtime: :class:`~axioma.core.sql.SqlRuntime`
		:return: количество измененных записей
		:rtype: :class:`int`
		:raises Runtime: :exc:`~axioma.common.RuntimeException` - Ошибка времени выполнения

		.. code-block:: python
			:caption: Пример использования
			:name: axioma.core.sql.update.code_sample

			# Демонстрация исключения 'Неизвестная колонка'
			from axioma.core.sql import *
			from axioma.common import RuntimeException

			# ...
			# context - Контекст таблиц, содержащий таблицу 'world'
			# ...

			try:
				query_text = 'UPDATE world SET {0}=\"{2}\" WHERE {0}=\"{1}\"'.format("a", "b", "c")
				res = update(query_text, context)
			except RuntimeException as ex:
				print("Ошибка: %s" % ex)

			# Вывод:
			# >>> Ошибка: Столбец 'a' не найден

	.. function:: remove(query_text, context, runtime)

		Запрос типа "Удаление" (DELETE)

		:param query_text: текст запроса
		:type query_text: :class:`str`
		:param context: контекст таблиц
		:type context: :class:`~axioma.core.sql.TableContext`
		:param runtime: среда выполнения запросов
		:type runtime: :class:`~axioma.core.sql.SqlRuntime`
		:return: количество удаленных записей
		:rtype: :class:`int`
		:raises Runtime: :exc:`~axioma.common.RuntimeException` - Ошибка времени выполнения

	.. function:: remove(query_text, context)

		Запрос типа "Удаление" (DELETE)

		:param query_text: текст запроса
		:type query_text: :class:`str`
		:param context: контекст таблиц
		:type context: :class:`~axioma.core.sql.TableContext`
		:param runtime: среда выполнения запросов
		:type runtime: :class:`~axioma.core.sql.SqlRuntime`
		:return: количество удаленных записей
		:rtype: :class:`int`
		:raises Runtime: :exc:`~axioma.common.RuntimeException` - Ошибка времени выполнения