Macros documentation
Filter
derive
The Filter
derive macro is attached on Sea ORM Models to generate structures and functions that are used by the QueryRoot to provide query functionality on Entities.
Attributes
#[sea_orm(table_name = "film")]
- table_name: used to supply the macro with the entity name that will be used for the structure names
Input
#[derive(
Clone,
Debug,
PartialEq,
DeriveModel,
DeriveActiveModel,
async_graphql::SimpleObject, // Required by Async GraphQL
seaography::macros::Filter, // The macro
)]
#[sea_orm(table_name = "film")]
#[graphql(complex)] // Used by Relations derive
#[graphql(name = "Film")] // Required by Async GraphQL
pub struct Model {
pub film_id: u16,
pub title: String,
pub rating: Option<Rating>,
pub last_update: DateTimeUtc,
}
Output
Used to describe complex SQL filters
#[derive(Debug, async_graphql::InputObject)]
#[graphql(name = "FilmFilter")]
pub struct Filter {
pub or: Option<Vec<Box<Filter>>>,
pub and: Option<Vec<Box<Filter>>>,
pub film_id: Option<seaography::TypeFilter<u16>>,
pub title: Option<seaography::TypeFilter<String>>,
// See Enumeration derive
pub rating: Option<crate::entities::sea_orm_active_enums::RatingEnumFilter>,
pub last_update: Option<seaography::TypeFilter<DateTimeUtc>>,
}
Used to receive a Filter
struct and convect it into sea_orm::Condition that is applied on sea_orm query statement
pub fn filter_recursive(root_filter: Option<Filter>) -> sea_orm::Condition {
...
}
Used to describe order by
#[derive(Debug, async_graphql::InputObject)]
#[graphql(name = "FilmOrderBy")]
pub struct OrderBy {
pub film_id: Option<seaography::OrderByEnum>,
pub title: Option<seaography::OrderByEnum>,
pub rating: Option<seaography::OrderByEnum>,
pub last_update: Option<seaography::OrderByEnum>,
}
Used to receive a query statement and OrderBy struct and update the statement with desired ordering.
pub fn order_by(stmt: sea_orm::Select<Entity>, order_by_struct: Option<OrderBy>) -> sea_orm::Select<Entity> {
...
}
RelationsCompact
derive
The RelationsCompact
derive macro is attached on Sea ORM Relation enum to generate structures and functions that are used by the Entity to query related Entities. This derive is applied on Entities in compact form.
Input
#[derive(
Copy,
Clone,
Debug,
EnumIter,
DeriveRelation,
seaography::macros::RelationsCompact,
)]
pub enum Relation {
#[sea_orm(
belongs_to = "super::employees::Entity",
from = "Column::SupportRepId",
to = "super::employees::Column::EmployeeId",
on_update = "NoAction",
on_delete = "NoAction"
)]
Employees,
#[sea_orm(has_many = "super::invoices::Entity")]
Invoices,
}
Output
The following are implemented for Entity Model:
// Requires graphql complex flag enabled on Model
#[async_graphql::ComplexObject]
impl Model {
pub fn employees<'a>(
&self,
ctx: &async_graphql::Context<'a>,
) -> Option<#return_type>
{
...
}
pub fn invoices<'a>(
&self,
ctx: &async_graphql::Context<'a>,
) -> Option<#return_type>
{
// Uses context.dataloader.load::<InvoicesFK>(...) to dispatch query
...
}
}
For every enum variant the following things are generated:
// Used for the context loader
#[derive(Clone, Debug)]
pub struct EmployeesFK(...);
// Implement load fn for Foreign key
#[async_trait::async_trait]
impl async_graphql::dataloader::Loader<EmployeesFK> for crate::OrmDataloader {
type Value = #return_type;
type Error = std::sync::Arc<sea_orm::error::DbErr>;
async fn load(
&self,
keys: &[#EmployeesFK],
) -> Result<
std::collections::HashMap<#EmployeesFK, Self::Value>,
Self::Error
>
{
...
}
}
relation
macro
The relation
macro is attached on Sea ORM RelationTrait implementation to generate structures and functions that are used by the Entity to query related Entities. This derive is applied on Entities in expanded form.
Input
#[seaography::macros::relation]
impl RelationTrait for Relation {
fn def(&self) -> RelationDef {
match self {
Self::Employees => Entity::belongs_to(super::employees::Entity)
.from(Column::SupportRepId)
.to(super::employees::Column::EmployeeId)
.into(),
Self::Invoices => Entity::has_many(super::invoices::Entity).into(),
}
}
}
Output
It produces the same result as RelationsCompact
EnumFilter
derive
The EnumFilter
macro is attached on Sea ORM Enum to generate its GraphQL filter struct used on Entities Filters
Input
#![doc = "SeaORM Entity. Generated by sea-orm-codegen 0.9.1"]
use sea_orm::entity::prelude::*;
#[derive(
Debug,
Clone,
PartialEq,
EnumIter,
DeriveActiveEnum,
Eq,
Copy,
async_graphql::Enum, // Required by GraphQL
seaography::macros::EnumFilter, // The macro
)]
#[sea_orm(rs_type = "String", db_type = "Enum", enum_name = "rating")]
pub enum Rating {
#[sea_orm(string_value = "G")]
G,
#[sea_orm(string_value = "PG")]
Pg,
#[sea_orm(string_value = "PG-13")]
Pg13,
#[sea_orm(string_value = "R")]
R,
#[sea_orm(string_value = "NC-17")]
Nc17,
}
Output
#[derive(Debug, async_graphql::InputObject)]
pub struct RatingEnumFilter {
pub eq: Option<Rating>,
pub ne: Option<Rating>,
pub gt: Option<Rating>,
pub gte: Option<Rating>,
pub lt: Option<Rating>,
pub lte: Option<Rating>,
pub is_in: Option<Vec<Rating>>,
pub is_not_in: Option<Vec<Rating>>,
pub is_null: Option<bool>,
}
QueryRoot
macro
The QueryRoot
derive macro is used to generate queries for every Entity that is defined through attributes. The query supports filtering, pagination and ordering.
Attributes
It enables the query for the specified path Entity
and it also instructs the QueryRoot
derive where to find the required utilities structures and functions for the generated code.
#[seaography(entity = "crate::entities::artists")]
Input
#[derive(Debug, seaography :: macros :: QueryRoot)]
#[seaography(entity = "crate::entities::artists")]
#[seaography(entity = "crate::entities::employees")]
pub struct QueryRoot;
Output
#[derive(Debug, async_graphql::InputObject)]
pub struct PageInput {
pub limit: usize,
pub page: usize,
}
#[derive(Debug, async_graphql::InputObject)]
pub struct CursorInput {
pub cursor: Option<String>,
pub limit: u64,
}
#[derive(async_graphql::OneofObject)]
pub enum Pagination {
Pages(PageInput),
Cursor(CursorInput),
}
/// Extra fields for pager pagination
#[derive(async_graphql::SimpleObject)]
pub struct ExtraPaginationFields {
pub pages: Option<usize>,
pub current: Option<usize>,
}
/// CursorValues is used to encode/decode the primary key of any Model for cursor pagination
#[derive(Debug)]
pub struct CursorValues(pub Vec<sea_orm::Value>);
impl async_graphql::types::connection::CursorType for CursorValues {
type Error = String;
/// Used to decode cursor String into a vector of Values
fn decode_cursor(s: &str) -> Result<Self, Self::Error> {
...
}
/// Used to encode a vector of Values into a cursor String
fn encode_cursor(&self) -> String {
...
}
}
/// Used to track the parsing state of the cursor String
#[derive(Debug)]
pub enum DecodeMode {
Type,
Length,
ColonSkip,
Data,
}
/// Used to parse a vector of Values into a ValueTuple enum
pub fn map_cursor_values(values: Vec<sea_orm::Value>) -> sea_orm::sea_query::value::ValueTuple {
...
}
#[async_graphql::Object]
impl QueryRoot {
pub async fn actor<'a>(
&self,
ctx: &async_graphql::Context<'a>,
filters: Option<crate::entities::actor::Filter>,
pagination: Option<Pagination>,
order_by: Option<crate::entities::actor::OrderBy>,
) -> async_graphql::types::connection::Connection<
String,
crate::entities::actor::Model,
ExtraPaginationFields,
async_graphql::types::connection::EmptyFields,
> {
// 1. use definitions
// 2. initialize db connection
// 3. create sql statement
// 4. apply filters and ordering
// 5. apply pagination
// 6. return result
}
pub async fn address<'a>(
&self,
ctx: &async_graphql::Context<'a>,
filters: Option<crate::entities::address::Filter>,
pagination: Option<Pagination>,
order_by: Option<crate::entities::address::OrderBy>,
) -> async_graphql::types::connection::Connection<
String,
crate::entities::address::Model,
ExtraPaginationFields,
async_graphql::types::connection::EmptyFields,
> {
...
}
}