rollun-datastore - это библиотека, которая предоставляет единый интерфейс взаимодействие с любым хранилищем данных
на основе Resource Query Language (RQL).
Существующие реализации: DbTable (для таблицы бд), CsvBase (для csv файлов), HttpClient (для внешнего ресурса через
http), Memory (для RAM).
- Документация
- Опис історії змін по версіям CHANGELOG.md
| Операция | HTTP | RQL (в query) | Тело запроса | Примечания | Заголовки и атрибуты запроса | Ограничения и известные проблемы |
|---|---|---|---|---|---|---|
| Создание записи (create) | POST | Нет | Объект | При коллизии ID поведение задаёт overwriteMode: false — ошибка; true — перезаписать существующую запись. Если PK указан и в path, и в body — приоритет у body. |
Опционально атрибут overwriteMode. Опционально атрибут primaryKeyValue. |
Если PK нет ни в body, ни в path, то попытка создания записи все равно произойдет для DbTable. Это может вызвать ошибку если PK не AUTO_INCREMENT. overwriteMode вызывает ошибку уровня deprecated для DbTable и по умолчанию имеет значение false |
| Множественное создание (multiCreate) | POST | Нет | Массив объектов | Пакетное создание. Обработчик вызывает multiCreate реализации. |
— | DbTable: атомарная транзакция, требуется PK в каждой записи; DataStoreAbstract: последовательные create() (не атомарно, ошибки игнорируются); HttpClient: требует поддержку сервера (X_MULTI_CREATE). |
| Получение записи (read) | GET | Нет | — | Требуется ID (в path). | Требуется атрибут primaryKeyValue |
— |
| Поиск (query) | GET | Обязателен | — | — | Атрибут primaryKeyValue должен отсутствовать |
— |
| Обновление записи (update) | PUT | Нет | Объект | ID обязателен; если указан и в path, и в body — приоритет у body. Upsert при overwriteMode = true (создать, если записи нет). |
Опционально атрибут overwriteMode. Опционально атрибут primaryKeyValue. |
overwriteMode вызывает ошибку уровня deprecated для DbTable и по умолчание имеет значение false. Согласно стандартам, частичное обновление записи должно выполнятся методом PATCH - об этом известно. |
| Множественное обновление (multiUpdate) | PUT | Нет | Массив объектов | Пакетное обновление. Обработчик вызывает multiUpdate реализации. |
— | DbTable: атомарная транзакция, все записи должны существовать, дубли ID запрещены; DataStoreAbstract: последовательные update() (не атомарно, ошибки игнорируются); HttpClient: требует поддержку сервера (X_MULTI_UPDATE). |
| Обновление по фильтру (queriedUpdate) | PATCH | Обязателен | Объект | Требуется наличие limit в RQL; нельзя select/groupBy; без PK (первичный ключ) в body. | Атрибут primaryKeyValue должен отсутствовать |
Для DbTable обновление по фильтру выполняется с помощью SELECT FOR UPDATE. |
| Удаление (delete) | DELETE | Нет | — | Требуется ID (в path). | Требуется атрибут primaryKeyValue. |
Для DbTable переданный в запросе PK быть либо типа integer, либо double, либо string. |
| Удаление по фильтру (queriedDelete) | В данный момент не реализовано | |||||
| Удаление всех записей (deleteAll) | В данный момент не реализовано | |||||
| Получение метаданных (getIdentifier) | HEAD | Нет | — | Метаданные/хедеры по PK. | — | Заголовки возвращаются в формате X_OPE_RATION и т.д. |
| Загрузить контент в CSV файле | GET | Можно | — | При экспорте RQL-ограничение limit(...) принудительно снимается обработчиком CSV, поэтому возвращается весь контент датастора. | Требуется заголовок download со значением csv |
В данный момент ситуация с limit это баг и о нём известно. Требуемый заголовок также в дальнейшем будет изменен согласно стандартам (Accept: text/csv). |
| Refresh (если поддерживается) | PATCH | Нет | — | Только для датасторов с RefreshableInterface. |
— | — |
| Пересоздание записи (rewrite) | В данный момент не реализовано | |||||
| Множественное пересоздание (multiRewrite) | В данный момент не реализовано |
Это атрибут запроса ($request->getAttribute('overwriteMode')), булев флаг, который middleware RequestDecoder
устанавливает на основании заголовка If-Match. Если заголовок равен * (If-Match: *) — значение true;
при любом другом значении или отсутствии заголовка — false. Он задает поведение при конфликте/отсутствии записи.
При экспорте CSV обработчик принудительно снимает/заменяет клиентский limit(...) на «без ограничений», поэтому выгружается всё (это поведение реализовано в CSV-хендлере).
Fallback применяется только если реализация не поддерживает multiCreate/multiUpdate (или в HttpClient сервер не
объявил поддержку через X_MULTI_CREATE/X_MULTI_UPDATE).
DATASTORE_MULTI_POLICY=strict(по умолчанию): fallback запрещен, выбрасываетсяDataStoreException.DATASTORE_MULTI_POLICY=soft: fallback разрешен, выполняется последовательный вызовcreate()/update()для каждого элемента. Ошибки отдельных элементов игнорируются (best-effort), возвращается список успешно обработанных идентификаторов.
Если переменная не задана или содержит любое другое значение — используется strict.
Это атрибут запроса ($request->getAttribute('primaryKeyValue')), строковый PK записи, который middleware ResourceResolver
извлекает из роут-параметра id или из последнего сегмента пути /api/datastore/{resourceName}/{id} (после rawurldecode(...)).
Если ID не задан — null.
В DataStore используется дополненная версия rawurlencode.
К перечню стандартных символов добавлены следующие преобразования
-=>%2D_=>%5F.=>%2E~=>%7E