<rst>RU::002-API::002-CometQL</rst>
<rst>Header: CometQL API</rst>

====== CometQL ======

**CometQL** - это api для работы с комет сервером по протоколу MySQL.

Преимущества CometQL
 
  -  Единый api для более чем 12 языков программирования
  -  Простой и понятный вид запросов
  -  В php есть средства поддержания постоянных соединений с MySQL и теперь их можно также использовать для работы с comet сервером.

В данном представлении данные лежат в таблицах а команды на выборку или вставку совершают какие-то действия.
Например, для получения информации о том, когда пользователь был online достаточно выполнить следующий запрос:
<code sql>select * from users_time where id = 2;</code>
Вот что мы увидим
<code sql>
mysql> select * from users_time where id in( 2, 3, 145);
+-----+------------+
| id  | time       |
+-----+------------+
| 2   | 0          |
| 3   | 1438245468 |
| 145 | -1         |
+-----+------------+
3 rows in set (0.31 sec)
</code>
Здесь пользователь с id = 2  в данный момент на сайте, пользователь с id = 3 был online 30 июля, а для пользователя с id = 145 нет данных.
===== Как подключится и попробовать самостоятельно =====
Вы можете сами подключится с демо данными и попробовать. Но подключатся рекомендуется через консоль, так как не все графические MySQL клиенты нормально работают с comet сервером. 
<code bash>
# Сервер app.comet-server.ru
# Логин 15
# Пароль lPXBFPqNg3f661JcegBY0N0dPXqUBdHXqj2cHf04PZgLHxT6z55e20ozojvMRvB8
# База данных CometQL_v1

# Строка для подключения из консоли
mysql -h app.comet-server.ru -u15 -plPXBFPqNg3f661JcegBY0N0dPXqUBdHXqj2cHf04PZgLHxT6z55e20ozojvMRvB8 -DCometQL_v1  --skip-ssl
</code>

Или ещё можете использовать [[comet:cometql:cli|онлайн командную строку]]. Она расположена в правом нижнем углу экрана на всех старицах.

<note tip>Есть [[comet:cometql:cli|пример исходных кодов на PHP с использованием CometQL]] для реализации онлайн командной строки</note>

<note important>Есть случаи когда нет возможности использовать протокол MySQL для соединения с комет сервером. Для таких случаев можно отправлять команды комет серверу по HTTP/HTTPS. Смотрите статью [[comet:cometql:HTTP|отправка CometQL запросов по HTTP]]</note>

Пример подключения к комет серверу из php. 
<code php>
$dev_id = "15"; // Используется как логин
$dev_key = "lPXBFPqNg3f661JcegBY0N0dPXqUBdHXqj2cHf04PZgLHxT6z55e20ozojvMRvB8"; // Используется как пароль

// Подключение выглядит как будто мы подключились к бд. Можно использовать функции для работы с mysql
// Но на самом деле вы подключаетесь к комет серверу. 
$link = mysqli_connect("app.comet-server.ru", $dev_id, $dev_key, "CometQL_v1");
if(!$link)
{  
    die("Не удалось создать соединение c CometQL");
}

$result = mysqli_query (  $link, "show status" ); 
if(mysqli_errno($link) != 0)
{
    echo "Error code:<a href='https://comet-server.com/wiki/doku.php/comet:cometql:error'  target='_blank' >".mysqli_errno($link)."</a>";
    echo "Error text:<a href='https://comet-server.com/wiki/doku.php/comet:cometql:error' target='_blank' >".mysqli_error($link)."</a>";
    exit;
}

while($row = mysqli_fetch_assoc($result))
{
    echo "<pre>";
    var_dump($row);
    echo "</pre><br>";
}  

</code>
====== Описание таблиц ====== 

<note important>Имена таблиц и колонок регистрозависимы и всегда пишутся в нижнем регистре.</note>

Замечания по реализации текущей версии CometQL:
  * В CometQL реализовано не всё, что доступно в sql. Часть функционала планируется реализовать позже. Но некоторые ограничения наложены специально в целях оптимизации внутренней структуры Comet сервера.
  * В целях [[comet:cometql:optimization_for_the_cluster|оптимизации внутренней логики]] операции delete и insert не возвращают количество затронутых строк, по крайней мере так будет в CometQL версии 1.0
  * Поддержка в запросах операторов OR, AND и ORDER BY будет реализована позже.

<note warning>У некоторых хостинг провайдеров установлен запрет на внешние соединения, это достаточно часто встречается на бесплатных или очень очень дешёвых хостингах. Для того, чтобы проверить возможность использования CometQL воспользуйтесь [[comet:testhosting|скриптом проверки хостинга]]. </note>
===== Таблица pipes_messages =====

Таблица pipes_messages содержит сообщения передаваемые через каналы. Для отправки сообщения в канал надо выполнить запрос вставки ( insert ) в эту таблицу.
<code sql>
mysql> insert into pipes_messages (name, event, message)values("pipe_name", "event_in_pipe", "text message");
Query OK, 0 rows affected (0.13 sec)
</code> 

Поля "name" и "event" должны соответствовать следующему <abbr>Цифры от 0 до 9 буквы английского алфавита и знаки = + / _ и длиной от 3 до 64 символов(регулярному выражению ^[0-9A-z=+/_]{3,64}$)</abbr>

<note tip>Узнать количество людей в канале можно сделав запрос к таблице "pipes" так как сообщение отправляется всем, кто подписался на канал, то таким образом можно узнать число людей, которые получили это сообщение.</note>
 
Запрос выборки из pipes_messages вернёт историю сообщений в канале, если функция сохранения истории включена для этого канала.
<code sql>
mysql> select * from pipes_messages where name = "p10";
+------+-------+-------+--------------+
| name | index | event | message      |
+------+-------+-------+--------------+
| p10  | 0     | event | msgData      |
| p10  | 1     | event | msgqqrrata   |
| p10  | 2     | evt3  | msgqqrrata   |
+------+-------+-------+--------------+
3 rows in set (0.00 sec)
</code>

Очищает историю сообщений в канале.
<code sql>
mysql> delete from pipes_messages where name = 'p10';
Query OK, 0 rows affected (0.13 sec)
</code>

=== Online пример ===
Введите имя канала "pipe_name" и нажмите подписаться.
<html>
<iframe src="//comet-server.com/doc/example/7/subscriptionTest.php" width="910px"></iframe>
</html>
А теперь с помощью online командной строки расположенной в углу экрана выполните запрос вставки в pipes_messages  и увидите что сообщение дошло.
<code sql>
mysql> insert into pipes_messages (name, event, message)values("pipe_name", "event_in_pipe", "text message");
</code> 
===== Таблица pipes  =====
Таблица pipes содержит информацию о том сколько человек подписались на сообщения из каналов. Таблица доступна только для чтения.
<code sql>
mysql> select * from pipes where name in( "web_admins", "web_php_chat");
+--------------+-------+
| name         | users |
+--------------+-------+
| web_admins   | 0     |
| web_php_chat | 0     |
+--------------+-------+
2 rows in set (0.30 sec)
</code>
 
=== Online пример ===

Выполните запрос
<code sql>
mysql> select * from pipes where name in( "web_admins", "web_php_chat");
</code>
Теперь введите имя канала "web_admins" и нажмите подписаться.
<html>
<iframe src="//comet-server.com/doc/example/7/subscriptionTest.php" width="910px"></iframe>
</html>
А теперь выполните запрос ещё раз и увидите что подписчиков в канале стало больше.
===== Таблица users_in_pipes =====
Таблица users_in_pipes содержит данные о том кто из пользователей подписался на канал. Таблица доступна только для чтения.
<code sql>
mysql> select * from users_in_pipes where name = "web_admins";
+------------+---------+-----------+-----------------+-------------------------------------+
| name       | user_id | ip        | origin          | language                            |
+------------+---------+-----------+-----------------+-------------------------------------+
| web_admins | 0       | 127.0.0.1 | https://site.ru | ru-RU,ru;q=0.8,en-US;q=0.6,en;q=0.4 |
| web_admins | 364     | 127.0.0.1 | https://site.ru | ru-RU,ru;q=0.8,en-US;q=0.6,en;q=0.4 |
+------------+---------+-----------+-----------------+-------------------------------------+
4 row in set (0.32 sec)
</code> 
Таблица имеет следующие поля: name, user_id, user_uuid, ip, origin, user_agent, language.
===== Таблица pipes_settings  =====
Таблица pipes_settings содержит настройки логирования каналов. По умолчанию сообщения проходящие через канал не запоминаются. Но если включить механизм логирования для канала то в комет сервере будет хранится n последних сообщений прошедших через этот канал.
Для включения механизма логирования в канале надо выполнить следующий запрос.
<code sql>
mysql> insert into pipes_settings ("name", "length") values ('p10', 10);
Query OK, 1 row affected (0.00 sec)
</code>
Здесь параметр length это то сколько последних сообщений будет запомнено. Принимает значения от 0 до 99.

Для того чтобы получить значения настроек канала нужно выполнить запрос выборки из pipes_settings.
<code sql>
mysql> select * from pipes_settings where name = 'p10';
+------+--------+
| name | length |
+------+--------+
| p10  | 10     |
+------+--------+
1 row in set (0.00 sec)
</code>

Для того чтобы отключить механизм логирования надо удалить из pipes_settings запись настроек.
<code sql>
mysql> delete from  pipes_settings where name = 'p10';
Query OK, 0 rows affected (0.00 sec)
</code>

===== Таблица users_messages =====
Таблица users_messages предназначена для отправки сообщений [[comet:authentication|авторизованным пользователям]] по их идентификатору.
<note tip>Отправка личных сообщений пользователям по их идентификаторам, а не в канал предоставляет более надёжную защиту передаваемых данных. А также повышает вероятность доставки сообщения пользователю.</note>
Например для отправки сообщения пользователю с id = 2 и текстом сообщения 'message' надо выполнить следующий запрос
<code sql>
mysql> insert into users_messages (id, event, message)values (2, 'event', 'message');
Query OK, 0 row affected (0.00 sec)
</code>
Сообщение либо отправлено пользователю сразу либо помещено в очередь для отправки пользователю позже. 

Для того чтобы получить все те сообщения которые ещё не доставлены пользователю и находятся в очереди надо выполнить запрос select
<code sql>
mysql> select * from users_messages where id = 2;
+----+-------+-------+---------+
| id | index | event | message |
+----+-------+-------+---------+
| 2  | 0     | evnt1 | message |
| 2  | 1     | evnt2 | messag2 |
+----+-------+-------+---------+
2 rows in set (0.00 sec)
</code>
Здесь видно что отправки ожидает 2 сообщения. Они будут отправлены сразу как пользователь появится online.
Таблица содержит 4 колонки.
  - id - Идентификатор пользователя
  - index - Номер сообщения в очереди
  - event - Имя события
  - message - Тело сообщения

Для очистки очереди используйте запрос удаления.
<code sql>
mysql> delete from users_messages where id = 2;
Query OK, 0 rows affected (0.08 sec)
</code>
<note>После того как сообщение будет доставлено пользователю оно автоматически удалится из очереди сообщений.</note>

===== Таблица users_time =====
Таблица users_time содержит данные о том когда были пользователи online. Таблица доступна только для чтения. Данные о времени хранятся в [[https://ru.wikipedia.org/wiki/UNIX-%D0%B2%D1%80%D0%B5%D0%BC%D1%8F|UNIX-time]]
<code sql>
mysql> select * from users_time where id in( 2, 3, 145);
+-----+------------+
| id  | time       |
+-----+------------+
| 2   | 0          |
| 3   | 1438245468 |
| 145 | -1         |
+-----+------------+
3 rows in set (0.31 sec)
</code>
Здесь пользователь с id = 2  в данный момент на сайте, пользователь с id = 3 был online 30 июля, а для пользователя с id = 145 нет данных.

<note>Есть пример использования данных из этой таблицы для того чтобы [[http://dimasudarkin.ru/%D0%BE%D0%BD%D0%BB%D0%B0%D0%B9%D0%BD-%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8C-%D0%B8%D0%BB%D0%B8-%D0%BD%D0%B5%D1%82-php/|определить, онлайн пользователь или нет]]</note>
===== Таблица users_auth =====

Таблица <abbr>Таблица содержит данные для авторизации пользователей на комет сервере(users_auth)</abbr>  содержит данные для [[comet:authentication|авторизации пользователей]] на комет сервере.

<code sql>
mysql> insert into users_auth (id, hash )values (12, 'hash1');
Query OK, 1 row affected (0.13 sec)

mysql> select * from users_auth where id in(2, 3, 12);
+----+----------------------------+
| id | hash                       |
+----+----------------------------+
| 2  | bjl6knotdb2t1oov958mhuian7 |
| 12 | hash1                      |
+----+----------------------------+
2 rows in set (0.32 sec)
</code>
Здесь для пользователя с id = 3 нет данных, а для пользователей 2 и 12 данные присутствуют.
<note important>В поле hash можно передавать только строки  длиной не более 32 символов и соответствующие <abbr>Цифры от 0 до 9 буквы английского алфавита и знаки = + / _ (регулярному выражению [0-9A-z=+/_])</abbr>.</note>
Для удаления данных [[comet:authentication|авторизации пользователей]] используйте запрос delete
<code sql>
delete from users_auth where id = 12;
Query OK, 0 rows affected (0.00 sec)
</code>
<note>В целях [[comet:cometql:optimization_for_the_cluster|оптимизации внутренней логики операции]] delete и insert не возвращают количество затронутых строк, по крайней мере так будет в QometQL версии 1.0</note>

===== Дополнительная информация =====

  * [[comet:cometql:cli|Пример использования CometQL на php]]
  * [[comet:cometql-bash-example|Пример отправки сообщения из bash]]
  * [[comet:cometql:error|Коды ошибок CometQL]]
  * [[comet:javascript_api:pipe-types|Зарезервированные имена каналов]]
  * [[comet:javascript_api|JavaScript API]]
  * [[comet:testhosting|Почему скрипт работает на локальной машине и не работает на хостинге? ]]
  * [[comet:dev_id|Что такое и зачем нужен "Публичный идентификатор разработчика" и "Секретный ключ разработчика"?]]
  * [[comet:faq:send-message-to-pipe|Как отправить сообщение в произвольный канал и как его потом получить на другой странице?]]
  * [[comet:faq:realtime-users-list|Как реализовать механизм отслеживания вхождения пользователей на сайт. То есть список посетителей обновляющийся на "лету"?]]
  * [[comet:saas|Могут ли влиять одни пользователи сервиса на других пользователей?]]  * 
  * [[comet:faq:access-to-channels-for-outsiders|Может ли кто то посторонний получать сообщение из каналов]]

====== Зарезервированные имена каналов ======

Основная статья [[comet:javascript_api:pipe-types|зарезервированные имена каналов]]
<note warning>Не рекомендуется использовать в своих проектах имена каналов вида "bin_*", "big_*", "push_*", "comet_*", "self_*", "trust_*" и "sys_*" эти имена возможно будут использованы для дальнейшего расширения функционала. И будут иметь какие ни будь не обычные свойства по сравнению с другими именами каналов.</note>


Так же есть каналы с особыми свойствами, о всех них ниже по тексту.
  * msg - Для доставки личных сообщений в соответствии с данными авторизации 
  * user_status_* - для автоматического уведомления JS api о статусе пользователей
  * web_* - Каналы в которые можно отправлять сообщения как из CometQL так и из JS api
  * track_* - для автоматического уведомления JS api о том что кто то подписался или отписался от этого канала

====== Обёртки над CometQL api ======

Если вы написали обёртку для работы с CometQL api для какого нибудь фреймворка то будет здорово если вы поделитесь своей наработкой с другими пользователями. Присылайте ссылки на репозиторий с вашей обёрткой на  support@comet-server.com 

====== Примечание ======

Для пользователей опенсорс версии полезно понимать что запросы попадающие в CometQL не передаются в бд комет сервера в MySQL они парсятся собственным парсером комет сервера. И таблицы из CometQL не являются прямым отражением таблиц из CometQL.