Руководство пользователя для разработчиков

Пакетные запросы

Пакетный запрос позволяет отправлять запросы с долгим временем обработки на процессоре. Обычно такие запросы вызывают ошибки таймаута при использовании SQL API. Чтобы избежать таймаутов, вы можете использовать пакетные запросы для создания, чтения и отмены запросов. Вы также можете запустить цепной пакетный запрос, чтобы объединить несколько SQL-запросов в одну задачу. Пакетный запрос планирует поступающие задачи и позволяет запрашивать статус задачи для каждого запроса.

Пакетные запросы не предназначены для больших полезных нагрузок запросов, содержащих более 16384 символов (16 КБ). Например, если вы вставляете большое количество строк в свою таблицу, вам все равно нужно использовать Import API или SQL API для этого типа управления данными. Пакетные запросы предназначены специально для запросов и использования процессора.

SQL API не предоставляет конечную точку для списка пакетных запросов (задач). Таким образом, при создании пакетного запроса (задачи) вы всегда должны сохранять идентификатор из ответа в качестве основной ссылки для последующих операций.

Аутентификация

Для управления вашими задачами требуется мастер-ключ API. Если вы не аутентифицированы, появится следующее сообщение об ошибке:

{
  "error": [
    "permission denied"
  ]
}

Чтобы получить полный доступ, вы должны использовать свой мастер-ключ API.

Используя инструмент cURL:

curl -X POST -H "Content-Type: application/json" -d '{
  "query": "{query}"
}' "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job?api_key={master_api_key}"

Используя клиент запроса Node.js:

var request = require("request");

var options = {
  method: "POST",
  url: "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job",
  qs: {
    "api_key": "{master_api_key}"
  },
  headers: {
    "content-type": "application/json"
  },
  body: {
    query: "{query}"
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Схема задания Batch Queries

Схема задания Batch Query в вашем аккаунте Epsilon Metrics включает следующие элементы. Только элемент query может быть изменен. Все другие элементы схемы задания определяются Batch Query и доступны только для чтения.

Имя	Описание
`job_id`	Универсальный уникальный идентификатор (uuid).
`user`	Идентификатор пользователя, отображаемый как имя пользователя.
`status`	Отображает результат долгосрочного запроса. Возможные результаты статуса:
	_ `pending`
	_ `running`
	_ `done`
	_ `failed`
	_ `canceled`
	_ `unknown`
`query`	SQL-запрос для выполнения в базе данных. Вы можете изменить оператор выбора SQL для использования в схеме задания. В некоторых сценариях вам может потребоваться получить результаты запроса из завершенного задания. См. Получение результатов задания для получения дополнительной информации.
`created_at`	Дата и время создания схемы задания.
`updated_at`	Дата и время последнего обновления или изменения схемы задания.
`failed_reason`	Отображает сообщение об ошибке базы данных, если что-то пошло не так.

Пример

HEADERS: 201 CREATED; application/json
BODY: {
  "job_id": "de305d54-75b4-431b-adb2-eb6b9e546014",
  "user": "cartofante",
  "query": "UPDATE airports SET type = 'international'",
  "status": "pending",
  "created_at": "2015-12-15T07:36:25Z",
  "updated_at": "2015-12-15T07:36:25Z"
}

Создать задание

Чтобы создать задание Batch Query, сделайте POST-запрос со следующими параметрами.

Создает запрос на задание Batch Query.

HEADERS: POST /api/v2/sql/job
BODY: {
  "query": "UPDATE airports SET type = 'international'"
}

Ответ

HEADERS: 201 CREATED; application/json
BODY: {
  "job_id": "de305d54-75b4-431b-adb2-eb6b9e546014",
  "user": "cartofante"
  "query": "UPDATE airports SET type = 'international'",
  "status": "pending",
  "created_at": "2015-12-15T07:36:25Z",
  "updated_at": "2015-12-15T07:36:25Z"
}

Примеры POST-запросов

Если вы используете операцию создания Batch Query для запроса POST с помощью cURL, используйте следующий код:

curl -X POST -H "Content-Type: application/json" -d '{
  "query": "CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)"
}' "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job"

Если вы используете операцию создания Batch Query для запроса POST с помощью клиента Node.js, используйте следующий код:

var request = require("request");

var options = {
  method: "POST",
  url: "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job",
  headers: { "content-type": "application/json" },
  body: {
    query: "CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)"
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Примечание: Всегда сохраняйте job_id из ответа для любой последующей операции, такой как чтение или удаление задания. Как упоминалось выше, SQL API не предоставляет конечных точек для получения списка заданий.

Чтение задания

Чтобы прочитать задание Batch Query, сделайте GET-запрос со следующими параметрами.

HEADERS: GET /api/v2/sql/job/de305d54-75b4-431b-adb2-eb6b9e546014
BODY: {}

Ответ

HEADERS: 200 OK; application/json
BODY: {
  "job_id": "de305d54-75b4-431b-adb2-eb6b9e546014",
  "user": "cartofante"
  "query": "UPDATE airports SET type = 'international'",
  "status": "pending",
  "created_at": "2015-12-15T07:36:25Z",
  "updated_at": "2015-12-15T07:36:25Z"
}

Примеры GET запросов

Если вы используете операцию чтения Batch Query для GET-запроса cURL, используйте следующий код:

curl -X GET "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job/{job_id}"

Если вы используете операцию чтения Batch Query для GET-запроса с клиентом Node.js, используйте следующий код:

var request = require("request");

var options = {
  method: "GET",
  url: "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job/{job_id}"
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Отмена задания

Чтобы отменить Batch Query, сделайте DELETE-запрос со следующими параметрами.

HEADERS: DELETE /api/v2/sql/job/de305d54-75b4-431b-adb2-eb6b9e546014
BODY: {}

Будьте внимательны при отмене задания, когда статус: pending или running.

Если задание находится в статусе pending, оно никогда не будет выполнено.
Если задание находится в статусе running, оно будет немедленно прервано.

Ответ

HEADERS: 200 OK; application/json
BODY: {
  "job_id": "de305d54-75b4-431b-adb2-eb6b9e546014",
  "user": "cartofante",
  "query": "UPDATE airports SET type = 'international'",
  "status": "cancelled",
  "created_at": "2015-12-15T07:36:25Z",
  "updated_at": "2015-12-17T06:22:42Z"
}

Задания могут быть отменены только при status: "running" или status: "pending", в противном случае операция Batch Query не разрешена. Вы получите ошибку, если статус задания отличается от “running” или “pending”.

errors: [
  "The job status is done, cancel is not allowed"
]

Примеры DELETE-запросов

Если вы используете операцию отмены Batch Query для DELETE-запроса cURL, используйте следующий код:

curl -X DELETE "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job/{job_id}"

Если вы используете операцию отмены Batch Query для DELETE-запроса с клиентом Node.js, используйте следующий код:

var request = require("request");

var options = {
  method: "DELETE",
  url: "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job/{job_id}",
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Цепочки пакетных запросов

В некоторых случаях вам может потребоваться объединить запросы в одну задачу. Опция “Цепочки пакетных запросов” позволяет выполнить массив SQL-запросов и определить порядок, в котором они выполняются. Вы можете использовать любые операции (создание, чтение, список, обновление, отмена) для запросов в цепочке пакетных запросов.

HEADERS: POST /api/v2/sql/job
BODY: {
  query: [
    "CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
    "DROP TABLE airports",
    "ALTER TABLE world_airports RENAME TO airport"
  ]
}

Ответ

HEADERS: 201 CREATED; application/json
BODY: {
  "job_id": "de305d54-75b4-431b-adb2-eb6b9e546014",
  "user": "cartofante",
  "query": [
    {
      "query": "CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
      "status": "pending"
    },
    {
      "query": "DROP TABLE airports",
      "status": "pending"
    },
    {
      "query": "ALTER TABLE world_airports RENAME TO airport",
      "status": "pending"
    }
  ],
  "status": "pending",
  "created_at": "2015-12-15T07:36:25Z",
  "updated_at": "2015-12-15T07:36:25Z"
}

Примечание: Пакетный запрос возвращает статус задачи как для родительского запроса Цепочки пакетных запросов, так и для каждого дочернего запроса внутри запроса. Порядок выполнения каждого запроса гарантируется. Вот возможные результаты статуса для Цепочек пакетных запросов:

Если один запрос в Цепочке пакетных запросов завершается с ошибкой, возвращается "status": "failed" как для задачи, так и для запроса, и все ожидающие запросы не будут обработаны.
Если вы отменяете задачу Цепочки пакетных запросов, статус задачи изменяется на "status": "cancelled". Все выполняющиеся запросы в рамках задачи будут остановлены и изменены на "status": "pending" и не будут обработаны.
Предположим, что статус первого запроса в работе равен "status": "done", второй запрос имеет статус "status": "running", а третий запрос имеет статус "status": "pending". Если второй запрос по какой-то причине завершится с ошибкой, статус задачи изменится на "status": "failed" и последний запрос не будет выполнен. В задаче Chained Batch Query указывается, какой запрос завершился с ошибкой.
Создание нескольких задач не гарантирует, что задачи будут выполнены в том же порядке, в котором они были созданы. Если вам нужно выполнить запросы в определенном порядке, вы можете использовать Chained Batch Queries.

Примеры POST

Если вы используете операцию Chained Batch Query для запроса POST с использованием cURL, используйте следующий код:

curl -X POST -H "Content-Type: application/json" -d '{
  "query": [
    "CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
    "DROP TABLE airports",
    "ALTER TABLE world_airports RENAME TO airport"
  ]
}' "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job"

Если вы используете операцию Chained Batch Query для запроса POST с использованием клиента Node.js, используйте следующий код:

var request = require("request");

var options = {
  method: "POST",
  url: "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job",
  headers: { "content-type": "application/json" },
  body: {
    "query": [
      "CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
      "DROP TABLE airports",
      "ALTER TABLE world_airports RENAME TO airport"
    ]
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Примеры PUT

Если вы используете операцию Chained Batch Query для запроса PUT с использованием cURL, используйте следующий код:

curl -X PUT -H "Content-Type: application/json" -d '{
  "query": [
    "CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
    "DROP TABLE airports",
    "ALTER TABLE world_airports RENAME TO airport",
    "UPDATE airports SET airport = upper(airport)"
  ]
}' "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job/{job_id}"

Если вы используете операцию Chained Batch Query для запроса PUT с использованием клиента Node.js, используйте следующий код:

var request = require("request");

var options = {
  method: "PUT",
  url: "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job/{job_id}",
  headers: { "content-type": "application/json" },
  body: {
    query: [
      "CREATE TABLE world_airports AS SELECT a.cartodb_id, a.the_geom, a.the_geom_webmercator, a.name airport, b.name country FROM world_borders b JOIN airports a ON ST_Contains(b.the_geom, a.the_geom)",
      "DROP TABLE airports",
      "ALTER TABLE world_airports RENAME TO airport",
      "UPDATE airports SET airport = upper(airport)"
    ]
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Объединение пакетных запросов с запасными вариантами

Когда вам нужно выполнить дополнительный запрос на основе того, как завершился цепочечный запрос, Batch Queries позволяет определить откаты onerror и onsuccess. Эта мощная функция открывает огромный диапазон возможностей, например:

Вы можете создавать периодические задания для получения обновленных данных и создания новой таблицы, где вы можете проверять статус своих таблиц.

Для этого примера вы можете создать следующее задание:

curl -X POST -H "Content-Type: application/json" -d '{
  "query": {
    "query": [{
      "query": "UPDATE nasdaq SET price = '\''$100.00'\'' WHERE company = '\''Epsilon Metrics'\''",
      "onsuccess": "UPDATE market_status SET status = '\''updated'\''', updated_at = NOW() WHERE table_name = '\''nasdaq'\''"
      "onerror": "UPDATE market_status SET status = '\''outdated'\''' WHERE table_name = '\''nasdaq'\''"
    }]
  }
}' "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job"

Если запрос успешно завершается, будет вызван откат onsuccess. В противном случае будет вызван onerror. Вы можете определить откаты для каждого запроса:

curl -X POST -H "Content-Type: application/json" -d '{
  "query": {
    "query": [{
      "query": "UPDATE nasdaq SET price = '\''$101.00'\'' WHERE company = '\''Epsilon Metrics'\''",
      "onsuccess": "UPDATE market_status SET status = '\''updated'\''', updated_at = NOW() WHERE table_name = '\''nasdaq'\''",
      "onerror": "UPDATE market_status SET status = '\''outdated'\''' WHERE table_name = '\''nasdaq'\''"
    }, {
      "query": "UPDATE down_jones SET price = '\''$100.00'\'' WHERE company = '\''Esri'\''",
      "onsuccess": "UPDATE market_status SET status = '\''updated'\''', updated_at = NOW() WHERE table_name = '\''down_jones'\''",
      "onerror": "UPDATE market_status SET status = '\''outdated'\''' WHERE table_name = '\''down_jones'\''"
    }]
  }
}' "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job"

…на уровне задания…

curl -X POST -H "Content-Type: application/json" -d '{
  "query": {
    "query": [{
      "query": "UPDATE nasdaq SET price = '\''$101.00'\'' WHERE company = '\''Epsilon Metrics'\''"
    }, {
      "query": "UPDATE down_jones SET price = '\''$100.00'\'' WHERE company = '\''Esri'\''"
    }],
    "onsuccess": "UPDATE market_status SET status = '\''updated'\''', updated_at = NOW()",
    "onerror": "UPDATE market_status SET status = '\''outdated'\'''"
  }
}' "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job"

Если запрос работы завершается с ошибкой (и определены откаты onerror для этого запроса и работы), то Batch Queries выполняет первый откат для этого запроса. Затем запускается откат работы и устанавливает статус работы как завершенной с ошибкой. Оставшиеся запросы не будут выполнены. Кроме того, Batch Queries выполнит откат onsuccess на уровне работы, если (и только если) каждый запрос был успешно завершен.

Шаблоны

Batch Queries предоставляет простой способ получения сообщения об ошибке и идентификатора работы, которые будут использоваться в ваших откатах, определенных на уровне запроса, с помощью следующих шаблонов:

<%= error_message %>: будет заменено сообщением об ошибке, сгенерированным базой данных.
<%= job_id %>: будет заменено идентификатором работы, предоставляемым Batch Queries.

Это полезно, когда вы хотите сохранить сообщения об ошибках в таблице:

curl -X POST -H "Content-Type: application/json" -d '{
  "query": {
    "query": [{
      "query": "UPDATE wrong_table SET price = '\''$100.00'\'' WHERE company = '\''Epsilon Metrics'\''",
      "onerror": "INSERT INTO errors_log (job_id, error_message, date) VALUES ('\''<%= job_id %>'\'', '\''<%= error_message %>'\'', NOW())"
    }]
  }
}' "https://maps.epsilonmetrics.ru/user/{user}/api/v2/sql/job"

Получение результатов работы

В некоторых сценариях вам может потребоваться получить результат работы. Если это так, оберните запрос в SELECT * INTO или CREATE TABLE AS. Результат будет сохранен в новой таблице вашей базы данных. Например, если используете запрос SELECT * FROM airports:

Оберните запрос SELECT * INTO job_result FROM (SELECT * FROM airports) AS job.
Создайте работу, как описано ранее.
После завершения работы получите результаты через Epsilon Metrics SQL API, SELECT * FROM job_result.

Примечание: Если вам нужно создать карту или анализ с новой таблицей, используйте функцию CDB_CartodbfyTable.

Лучшие практики

Для лучших практик следуйте этим рекомендуемым заметкам об использовании при работе с Batch Queries:

Batch Queries рекомендуется использовать для запросов INSERT, UPDATE и CREATE, которые манипулируют и создают новые данные, такие как создание дорогостоящих индексов, применение обновлений на больших таблицах и создание таблиц из сложных запросов. Batch Queries не влияет на запросы SELECT, которые извлекают данные, но не сохраняют результаты в таблице. Например, выполнение пакетного запроса с использованием SELECT * from my_dataset не даст никаких результатов.
Batch Queries не предназначены для больших запросов с большим объемом данных (например: вставка тысяч строк). Вместо этого используйте Import API для этого типа управления данными.
Существует ограничение в 16 КБ на одну работу. Если размер вашей работы превышает это значение, появится следующее сообщение об ошибке:

Ваш запрос слишком велик. Максимальный допустимый размер составляет 16384 (16 КБ)

Следуя этим рекомендациям, вы сможете эффективно использовать Batch Queries для работы с вашими данными и обеспечения успешного выполнения запросов.