Firebase SQL Connect позволяет создавать коннекторы для экземпляров PostgreSQL, управляемых с помощью Cloud SQL. Эти коннекторы представляют собой комбинации запросов и мутаций для использования данных из вашей схемы.
В руководстве по началу работы мы представили схему приложения для отзывов о фильмах для PostgreSQL.
В этом руководстве также представлены как развертываемые, так и специальные административные операции, включая запросы.
- Развертываемые запросы – это запросы, которые вы реализуете для вызова из клиентских приложений с помощью определенных вами конечных точек API. Вы объединяете их в коннектор, развернутый на сервере. Инструменты SQL Connect генерируют клиентские SDK на основе вашего API. Развернутые запросы не защищены правилами IAM, поэтому обязательно защитите их с помощью директивы SQL Connect
@auth. - Специальные административные запросы выполняются из сред с повышенными привилегиями для чтения данных. Вы можете создавать и выполнять их в консоли Firebase или в локальных средах разработки с помощью нашего расширения SQL Connect VS Code.
В этом руководстве подробно рассматриваются развертываемые запросы.
Особенности запросов SQL Connect
SQL Connect позволяет выполнять базовые запросы всеми способами, которые вы ожидаете от базы данных PostgreSQL.
Но с расширениями SQL Connect для GraphQL вы можете реализовать расширенные запросы для более быстрых и эффективных приложений:
- Используйте ключевые скаляры, возвращаемые многими операциями, чтобы упростить повторяющиеся операции с записями.
- Выполнять запросы в ходе многоэтапных операций изменения для поиска данных, сокращая количество строк кода и обращений к серверу.
Как создавать запросы с помощью сгенерированных полей
Операции SQL Connect расширят набор полей, автоматически созданных SQL Connect на основе типов и отношений между ними в вашей схеме. Эти поля генерируются локальными инструментами при каждом изменении схемы.
С помощью сгенерированных полей можно создавать сложные запросы, например для получения отдельных или нескольких записей из одной таблицы или нескольких записей из связанных таблиц.Предположим, что ваша схема содержит тип Movie и связанный с ним тип Actor.
SQL Connect генерирует поля movie, movies, actors_on_movies и другие.
Запрос с полем
movie
|
Поле |
Используйте это поле, чтобы запросить один фильм по его ключу. query GetMovie($myKey: Movie_Key!) { movie(key: $myKey) { title } } |
Запрос с полем
movies
|
Поле |
Это поле позволяет запрашивать данные о нескольких фильмах, например обо всех фильмах, выпущенных в определенном году. query GetMovies($myYear: Int!) { movies(where: { year: { eq: $myYear } }) { title } } |
Запрос с полем
actors_on_movies
|
Поле |
Используйте это поле, чтобы запросить всех актеров, связанных с определенным фильмом. query GetActorsOnMovie($myKey: Movie_Key!) { actors_on_movies(where: { movie: { key: { eq: $myKey } } }) { actor { name } } } |
Основные элементы запроса
Запросы SQL Connect – это запросы GraphQL с расширениями SQL Connect. Как и в случае с обычным запросом GraphQL, вы можете определить название операции и список переменных GraphQL.
SQL Connect расширяет запросы GraphQL с помощью настраиваемых директив, таких как @auth.
В следующем запросе:
- Определение типа
query - Название операции (запроса)
ListMoviesByGenre - Один аргумент запроса, в данном случае переменная
$genreтипаString. - Одна директива
@auth. - Одно поле
movies.
query ListMoviesByGenre($genre: String!) @auth(level: PUBLIC) {
movies(where: { genre: { eq: $genre } }) {
id
title
}
}
Для каждого аргумента запроса требуется объявление типа, встроенного, например String, или пользовательского, определенного схемой, например Movie.
В этом руководстве мы рассмотрим сигнатуры запросов разной сложности. В конце вы познакомитесь с мощными и лаконичными выражениями отношений, которые можно использовать для создания развертываемых запросов.
Ключевые скаляры в запросах
Но сначала несколько слов о ключевых скалярах.
SQL Connect определяет специальный скалярный ключ, представляющий первичные ключи каждой таблицы, идентифицируемые по {TableType}_Key. Это объект JSON со значениями первичного ключа.
Вы получаете ключевые скаляры в качестве ответа, возвращаемого большинством автоматически сгенерированных полей чтения, или, конечно, из запросов, в которых вы получили все поля, необходимые для построения скалярного ключа.
Одиночные автоматические запросы, такие как movie в нашем примере, поддерживают аргумент key, который принимает скаляр ключа.
Вы можете передать скаляр ключа в виде литерала. Но вы можете определить переменные, чтобы передавать ключевые скаляры в качестве входных данных.
Запрос
query GetMovie($myKey: Movie_Key!) { movie(key: $myKey) { title } }
Ответ
{ "data": { "movie": { "title": "Example Movie Title" } } }
Их можно указать в запросе JSON, как показано ниже (или в других форматах сериализации):
{
# …
"variables": {
"myKey": {"id": "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"}
}
}
Благодаря синтаксическому анализу пользовательских скаляров Movie_Key также можно создать с помощью синтаксиса объекта, который может содержать переменные. Это может быть полезно, если вы хотите разбить отдельные компоненты на разные переменные.
Как создавать простые запросы
Вы можете начать писать запросы, чтобы получать отдельные записи из базы данных или перечислять записи из таблицы с возможностью ограничения и упорядочивания результатов.
Как получить отдельные записи
Самый простой запрос получает одну запись по идентификатору. В запросе будет использоваться автоматически созданное поле movie.
Запрос
query GetMovieById($id: UUID!) @auth(level: PUBLIC) { movie(id: $id) { id title imageUrl genre } }
Ответ
{ "data": { "movie": { "id": "some-uuid", "title": "Example Movie Title", "imageUrl": "https://example.com/movie.jpg", "genre": "Action" } } }
Получить все записи в таблице
Чтобы получить подмножество полей для полного списка фильмов из таблицы Movies, в запросе будет использоваться автоматически созданное поле movies. Реализация может выглядеть следующим образом:
Запрос
query ListMovies @auth(level: PUBLIC) { movies { id title imageUrl genre } }
Ответ
{ "data": { "movies": [ { "id": "some-uuid", "title": "Example Movie Title", "imageUrl": "https://example.com/movie.jpg", "genre": "Action" }, { "id": "another-uuid", "title": "Another Movie Title", "imageUrl": "https://example.com/another-movie.jpg", "genre": "Comedy" } ] } }
Используйте операторы orderBy, limit и offset
Естественно, что вывод всех записей из таблицы имеет ограниченную полезность.
Вы можете упорядочивать результаты и разбивать их на страницы. Эти аргументы принимаются, но не возвращаются в результатах.
В этом примере запрос получает названия 10 лучших фильмов по рейтингу.
Запрос
query MoviesTop10 { movies(orderBy: [{ rating: DESC }], limit: 10) { # graphql: list the fields from the results to return title } }
Ответ
{ "data": { "movies": [ { "title": "Top Movie 1" }, { "title": "Top Movie 2" }, { "title": "Top Movie 3" } // ... other 7 movies ] } }
Вам может понадобиться получить строки со смещением, например фильмы с 11 по 20, упорядоченные по рейтингу.
Запрос
query Movies11to20 { movies(orderBy: [{ rating: DESC }], limit: 10, offset: 10) { # graphql: list the fields from the results to return title } }
Ответ
{ "data": { "movies": [ { "title": "Movie 11" }, { "title": "Movie 12" }, { "title": "Movie 13" } // ... other 7 movies ] } }
Как использовать псевдонимы в запросах
SQL Connect поддерживает псевдонимы GraphQL в запросах. С помощью псевдонимов вы переименовываете данные, возвращаемые в результатах запроса. Один запрос SQL Connect может применять несколько фильтров или других операций в одном эффективном запросе к серверу, фактически выдавая несколько "подзапросов" одновременно. Чтобы избежать конфликтов имен в возвращаемом наборе данных, вы используете псевдонимы для различения подзапросов.
Ниже приведен запрос, в котором выражение использует псевдонимы mostPopular и leastPopular.
Запрос
query ReviewPopularitySpread($genre: String) { mostPopular: review( first: { where: {genre: {eq: $genre}}, orderBy: {popularity: DESC} } ), leastPopular: review( last: { where: {genre: {eq: $genre}}, orderBy: {popularity: DESC} } ) }
Ответ
{ "data": { "mostPopular": [ { "popularity": 9 } ], "leastPopular": [ { "popularity": 1 } ] } }
Как использовать фильтры запросов
Запросы SQL Connect сопоставляются со всеми распространенными фильтрами SQL и операциями сортировки.
Фильтр where с операторами orderBy
Возвращает все совпадающие строки из таблицы (и вложенных ассоциаций). Если ни одна запись не соответствует фильтру, возвращается пустой массив.
Запрос
query MovieByTopRating($genre: String) { mostPopular: movies( where: { genre: { eq: $genre } }, orderBy: { rating: DESC } ) { # graphql: list the fields from the results to return id title genre description } }
Ответ
{ "data": { "mostPopular": [ { "id": "some-uuid", "title": "Example Movie Title", "genre": "Action", "description": "A great movie" } ] } }
Фильтрация по нулевым значениям
Проверить значения null можно с помощью оператора isNull.
Запрос
query ListMoviesWithoutDescription { movies(where: { description: { isNull: true }}) { id title } }
Ответ
{ "data": { "movies": [ { "id": "some-uuid", "title": "Example Movie Title" }, { "id": "another-uuid", "title": "Another Movie Title" } ] } }
Дополнительные операторы перечислены в справочном руководстве по типам входных объектов.
Фильтрация по сравнению значений
Для сравнения значений в запросах можно использовать операторы, например lt (меньше) и ge (больше или равно).
Запрос
query ListMoviesByRating($minRating: Int!, $maxRating: Int!) { movies(where: { rating: { ge: $minRating, lt: $maxRating }}) { id title } }
Ответ
{ "data": { "movies": [ { "id": "some-uuid", "title": "Example Movie Title" }, { "id": "another-uuid", "title": "Another Movie Title" } ] } }
Фильтрация с помощью операторов includes и excludes для полей массива
Вы можете проверить, содержит ли поле массива указанный элемент.
В примере ниже показано, как использовать оператор includes.
SQL Connect поддерживает includesAll, excludes, excludesAll и другие форматы. Полный список операторов для целых чисел, строк, дат и других типов данных приведен в _ListFilter справочной документации.
Запрос
query ListMoviesByTag($tag: String!) { movies(where: { tags: { includes: $tag }}) { # graphql: list the fields from the results to return id title } }
Ответ
{ "data": { "movies": [ { "id": "some-uuid", "title": "Example Movie Title" } ] } }
Фильтрация с помощью строковых операций и регулярных выражений
В запросах можно использовать стандартные операции поиска и сравнения строк, в том числе регулярные выражения. Обратите внимание, что для эффективности вы объединяете здесь несколько операций и устраняете их неоднозначность с помощью псевдонимов.
query MoviesTitleSearch($prefix: String, $suffix: String, $contained: String, $regex: String) {
prefixed: movies(where: {title: {startsWith: $prefix}}) {...}
suffixed: movies(where: {title: {endsWith: $suffix}}) {...}
contained: movies(where: {title: {contains: $contained}}) {...}
}
Фильтр с логикой операторов _or, _and, _not
Для более сложной логики используйте _or. SQL Connect также поддерживает операторы _and и _not.
Запрос
query ListMoviesByGenreAndGenre($minRating: Int!, $genre: String) { movies( where: { _or: [{ rating: { ge: $minRating } }, { genre: { eq: $genre } }] } ) { # graphql: list the fields from the results to return title } }
Ответ
{ "data": { "movies": [ { "title": "Movie Title 1" }, { "title": "Movie Title 2" } ] } }
Как писать реляционные запросы
Запросы SQL Connect могут получать доступ к данным на основе связей между таблицами. Вы можете использовать отношения объектов (один к одному) или массивов (один ко многим), определенные в вашей схеме, чтобы создавать вложенные запросы, то есть получать данные для одного типа вместе с данными из вложенного или связанного типа.
В таких запросах используется синтаксис magic SQL Connect _on_ и _via в сгенерированных полях чтения.
Ознакомьтесь с примером схемы.
Многие к одному
Теперь рассмотрим запрос, иллюстрирующий синтаксис _on_.
Запрос
query MyReviews @auth(level: USER) { user(key: {id_expr: "auth.uid"}) { reviews: reviews_on_user { movie { name } rating } } }
Ответ
{ "data": { "user": { "reviews": [ { "movie": { "name": "Movie Title" }, "rating": 5 } ] } } }
Один на один
Вы можете написать запрос "один к одному", используя синтаксис _on_.
Запрос
query GetMovieMetadata($id: UUID!) @auth(level: PUBLIC) { movie(id: $id) { movieMetadatas_on_movie { director } } }
Ответ
{ "data": { "movie": { "movieMetadatas_on_movie": { "director": "Some Director" } } } }
Многие ко многим
В запросах "многие ко многим" используется синтаксис _via_. Запрос «многие ко многим» может
извлекать актеров для указанного фильма.
Запрос
query MoviesActors($id: UUID!) @auth(level: USER) { movie(id: $id) { actors: actors_via_MovieActors { name } } }
Ответ
{ "data": { "movie": { "actors": [ { "name": "Actor Name" } ] } } }
Но мы можем написать более сложный запрос с использованием псевдонимов, чтобы отфильтровать результаты по role и получить актеров и связанные с ними фильмы в результатах mainActors и supportingActors. Поскольку это отношение "многие ко многим", используется синтаксис _via_.
Запрос
query GetMovieCast($movieId: UUID!, $actorId: UUID!) @auth(level: PUBLIC) { movie(id: $movieId) { mainActors: actors_via_MovieActor(where: { role: { eq: "main" } }) { name } supportingActors: actors_via_MovieActor( where: { role: { eq: "supporting" } } ) { name } } actor(id: $actorId) { mainRoles: movies_via_MovieActor(where: { role: { eq: "main" } }) { title } supportingRoles: movies_via_MovieActor( where: { role: { eq: "supporting" } } ) { title } } }
Ответ
{ "data": { "movie": { "mainActors": [ { "name": "Main Actor Name" } ], "supportingActors": [ { "name": "Supporting Actor Name" } ] }, "actor": { "mainRoles": [ { "title": "Main Role Movie Title" } ], "supportingRoles": [ { "title": "Supporting Role Movie Title" } ] } } }
Запросы агрегирования
Что такое агрегированные данные и зачем они нужны?
Агрегированные поля позволяют выполнять вычисления со списком результатов. С помощью агрегированных полей можно:
- Как найти среднюю оценку отзыва
- Как узнать общую стоимость товаров в корзине
- Найти товар с самым высоким или низким рейтингом
- Подсчитайте количество товаров в магазине.
Агрегирование выполняется на сервере, что дает ряд преимуществ по сравнению с расчетом на стороне клиента:
- Повышение производительности приложения (поскольку вы избегаете вычислений на стороне клиента).
- Снижение расходов на исходящий трафик (поскольку вы отправляете только агрегированные результаты, а не все входные данные).
- Повышенная безопасность (поскольку вы можете предоставить клиентам доступ к агрегированным данным, а не ко всему набору данных).
Пример схемы для агрегированных данных
В этом разделе мы перейдем к примеру схемы витрины магазина, которая хорошо подходит для объяснения того, как использовать агрегаты:
type Product @table {
name: String!
manufacturer: String!
quantityInStock: Int!
price: Float!
expirationDate: Date
}
Простое агрегирование
_count для всех полей
Простейшее агрегированное поле – _count. Оно возвращает количество строк, соответствующих запросу. Для каждого поля в вашем типе SQL Connect генерирует соответствующие агрегированные поля в зависимости от типа поля.
Запрос
query CountProducts {
products {
_count
}
}
Ответ one
one
Например, если в вашей базе данных 5 товаров, результат будет следующим:
{
"products": [
{
"_count": 5
}
]
}
Во всех полях есть поле <field>_count, в котором указано, сколько строк имеют ненулевое значение в этом поле.
Запрос
query CountProductsWithExpirationDate {
products {
expirationDate_count
}
}
Ответfield_count
field_count
Например, если у вас есть три товара со сроком окончания действия, результат будет следующим:
{
"products": [
{
"expirationDate_count": 3
}
]
}
_min, _max, _sum и _avg для числовых полей;
Числовые поля (int, float, int64) также имеют <field>_min, <field>_max, <field>_sum и <field>_avg.
Запрос
query NumericAggregates {
products {
quantityInStock_max
price_min
price_avg
quantityInStock_sum
}
}
Ответ_min _max _sum _avg
_min _max _sum _avg
Например, у вас есть следующие товары:
- Товар А:
quantityInStock: 10,price: 2.99 - Товар Б:
quantityInStock: 5,price: 5.99 - Товар C:
quantityInStock: 20,price: 1.99
Результат будет следующим:
{
"products": [
{
"quantityInStock_max": 20,
"price_min": 1.99,
"price_avg": 3.6566666666666666,
"quantityInStock_sum": 35
}
]
}
_min и _max для дат и временных меток
Поля даты и временной метки содержат <field>_min и <field>_max.
Запрос
query DateAndTimeAggregates {
products {
expirationDate_max
expirationDate_min
}
}
Ответ_min _maxdatetime
_min _maxdatetime
Например, если у вас есть следующие сроки действия:
- Товар А:
2024-01-01 - Товар Б:
2024-03-01 - Товар В:
2024-02-01
Результат будет следующим:
{
"products": [
{
"expirationDate_max": "2024-03-01",
"expirationDate_min": "2024-01-01"
}
]
}
Заметно
Аргумент distinct позволяет получить все уникальные значения для поля (или комбинации полей). Пример:
Запрос
query ListDistinctManufacturers {
products(distinct: true) {
manufacturer
}
}
Ответdistinct
distinct
Например, если у вас есть следующие производители:
- Товар А:
manufacturer: "Acme" - Товар Б:
manufacturer: "Beta" - Товар В:
manufacturer: "Acme"
Результат будет следующим:
{
"products": [
{ "manufacturer": "Acme" },
{ "manufacturer": "Beta" }
]
}
Вы также можете использовать аргумент distinct для агрегированных полей, чтобы агрегировать отдельные значения. Пример:
Запрос
query CountDistinctManufacturers {
products {
manufacturer_count(distinct: true)
}
}
Ответdistinctonaggregate
distinctonaggregate
Например, если у вас есть следующие производители:
- Товар А:
manufacturer: "Acme" - Товар Б:
manufacturer: "Beta" - Товар В:
manufacturer: "Acme"
Результат будет следующим:
{
"products": [
{
"manufacturer_count": 2
}
]
}
Сгруппированные агрегированные данные
Чтобы выполнить групповое агрегирование, выберите сочетание агрегированных и неагрегированных полей в типе. В результате все строки, имеющие одинаковое значение в неагрегированных полях, будут объединены в группу, а для агрегированных полей будет рассчитано общее значение. Пример:
Запрос
query MostExpensiveProductByManufacturer {
products {
manufacturer
price_max
}
}
Ответgroupedaggregates
groupedaggregates
Например, у вас есть следующие товары:
- Товар А:
manufacturer: "Acme",price: 2.99 - Товар Б:
manufacturer: "Beta",price: 5.99 - Товар C:
manufacturer: "Acme",price: 1.99
Результат будет следующим:
{
"products": [
{ "manufacturer": "Acme", "price_max": 2.99 },
{ "manufacturer": "Beta", "price_max": 5.99 }
]
}
having и where со сгруппированными агрегированными данными
Вы также можете использовать аргументы having и where, чтобы возвращать только группы, соответствующие заданным критериям.
havingпозволяет фильтровать группы по их агрегированным полям.whereпозволяет фильтровать строки по неагрегированным полям.
Запрос
query FilteredMostExpensiveProductByManufacturer {
products(having: {price_max: {ge: 2.99}}) {
manufacturer
price_max
}
}
Ответhavingwhere
havingwhere
Например, у вас есть следующие товары:
- Товар А:
manufacturer: "Acme",price: 2.99 - Товар Б:
manufacturer: "Beta",price: 5.99 - Товар C:
manufacturer: "Acme",price: 1.99
Результат будет следующим:
{
"products": [
{ "manufacturer": "Acme", "price_max": 2.99 },
{ "manufacturer": "Beta", "price_max": 5.99 }
]
}
Агрегирование данных из нескольких таблиц
Агрегированные поля можно использовать вместе со сгенерированными полями с отношением "один ко многим", чтобы отвечать на сложные вопросы о данных. Ниже приведена измененная схема с отдельной таблицей Manufacturer, которую мы можем использовать в примерах.
type Product @table {
name: String!
manufacturer: Manufacturer!
quantityInStock: Int!
price: Float!
expirationDate: Date
}
type Manufacturer @table {
name: String!
headquartersCountry: String!
}
Теперь мы можем использовать агрегированные поля, чтобы, например, узнать, сколько товаров производит производитель:
Запрос
query GetProductCount($id: UUID) {
manufacturers {
name
products_on_manufacturer {
_count
}
}
}
Ответ aggregatesacrosstables
aggregatesacrosstables
Например, если у вас есть следующие производители:
- Производитель A:
name: "Acme",products_on_manufacturer: 2 - Производитель B:
name: "Beta",products_on_manufacturer: 1
Результат будет следующим:
{
"manufacturers": [
{ "name": "Acme", "products_on_manufacturer": { "_count": 2 } },
{ "name": "Beta", "products_on_manufacturer": { "_count": 1 } }
]
}
Поля перечисления запросов
Вы можете запрашивать поля перечисления в схеме.
Предположим, что наше перечисление реализовано следующим образом:
enum AspectRatio {
ACADEMY
WIDESCREEN
ANAMORPHIC
IMAX
"No information available on aspect ratio"
UNAVAILABLE
}
Например, вы можете посмотреть список всех фильмов с нужным соотношением сторон.
query ListMoviesByAspectRatio($aspectRatio: AspectRatio!) @auth(level: PUBLIC) {
movies(where:
{originalAspectRatio: {eq: $aspectRatio}}
) {
id
title
imageUrl
releaseYear
genre
rating
tags
description
otherAspectRatios
}
}
Как фильтровать поля перечисления
Для перечислений доступны стандартные действия фильтрации: eq, ne, ge, gt, lt, le, in, nin, а также includes, excludes, includesAll и excludesAll для списков.
В order операторы "больше" и "меньше" используют порядок значений перечисления для выполнения. Значения в начале перечисления меньше, чем в конце.
Например, следующий пункт where вернет все фильмы с ratio меньше входного соотношения сторон.
- В первом примере, если бы
$aspectRatioбыло IMAX, то были бы выбраны фильмы сratio, соответствующим ACADEMY, WIDESCREEN и ANAMORPHIC. - Во втором примере будут возвращены только фильмы, доступные в обоих форматах.
movies(where: {originalAspectRatio: {lt: $aspectRatio}})
movies(where: {otherAspectRatios: {includesAll: [ACADEMY, WIDESCREEN]}})
Как выполнять запросы на агрегирование полей перечисления
Для перечислений поддерживается только _count.
Следующий запрос подсчитывает общее количество фильмов с каждым соотношением сторон.
query MovieCountByOriginalAspectRatio @auth(level: PUBLIC) {
movies {
_count
originalAspectRatio
}
}
Вызов запросов перечисления из клиентского кода
Узнайте, как использовать запросы перечисления от клиентов и как разрабатывать вызовы клиентов, чтобы максимально повысить гибкость управления перечислениями, в руководствах по SDK для iOS, Android, веб-приложений и Flutter.
Как создавать расширенные запросы: используйте поля query, чтобы считывать данные в многоэтапных операциях
Во многих ситуациях вам может потребоваться прочитать базу данных во время выполнения мутации, чтобы найти и проверить существующие данные перед выполнением, например, вставок или обновлений. Эти параметры позволяют сократить количество операций обмена данными и, следовательно, расходы.
SQL Connect поддерживает эту функцию. Подробнее о многоэтапных операциях…
Дальнейшие действия
Вас может заинтересовать:
- Генерировать запросы для приложений с помощью инструментов на основе ИИ.
- Авторизуйте запросы в соответствии с руководством по авторизации.
- Вызов запросов из клиентского кода для веб-приложений, iOS, Android и Flutter.