Seaography

https://docs.rs/crate/seaography/2.0.0-rc.1
Admin
Seaography is a GraphQL framework and code generator for SeaORM that automatically generates...
Tokens:7,886
Snippets:57
Trust Score:9.7
Update:10 months ago
Show doc for...
Tokens:
Raw
### PostgreSQL Database Setup

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/source/README

Instructions for setting up the Sakila sample database with PostgreSQL and generating Seaography entities.

```APIDOC
## PostgreSQL Setup

### Description
Setup the [sakila](https://github.com/SeaQL/seaography/blob/main/examples/postgres/sakila-schema.sql) sample database and generate Seaography entities for PostgreSQL.

### Steps
1. **Setup Database**: Ensure the Sakila sample database is set up for PostgreSQL.
2. **Generate Entities**: Use `sea-orm-cli` to generate entities.
   ```sh
   cd examples/postgres
   sea-orm-cli generate entity -o src/entities -u postgres://user:pw@localhost/sakila --seaography
   ```
3. **Generate Seaography CLI**: Use `seaography-cli` to generate Seaography schema.
   ```sh
   seaography-cli ./ src/entities postgres://user:pw@localhost/sakila seaography-postgres-example
   ```
4. **Run Application**: Compile and run the Rust application.
   ```sh
   cargo run
   ```

### Request Example
None (This section describes command-line operations for setup).

### Response
None (This section describes command-line operations for setup).
```

--------------------------------

### PostgreSQL Setup for Seaography with Sea-ORM CLI

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/index

This snippet shows the commands to set up a PostgreSQL database for Seaography. It involves navigating to the examples directory, generating Sea-ORM entities from a Sakila database, and then running the Seaography CLI to generate PostgreSQL-specific code.

```bash
cd examples/postgres
sea-orm-cli generate entity -o src/entities -u postgres://user:pw@localhost/sakila --seaography
seaography-cli ./ src/entities postgres://user:pw@localhost/sakila seaography-postgres-example
cargo run
```

--------------------------------

### SQLite Database Setup

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/source/README

Instructions for setting up the Sakila sample database with SQLite and generating Seaography entities.

```APIDOC
## SQLite Setup

### Description
Setup the Sakila sample database with SQLite and generate Seaography entities.

### Steps
1. **Setup Database**: Ensure the Sakila sample database is set up for SQLite (e.g., `sakila.db` file).
2. **Generate Entities**: Use `sea-orm-cli` to generate entities.
   ```sh
   cd examples/sqlite
   sea-orm-cli generate entity -o src/entities -u sqlite://sakila.db --seaography
   ```
3. **Generate Seaography CLI**: Use `seaography-cli` to generate Seaography schema.
   ```sh
   seaography-cli ./ src/entities sqlite://sakila.db seaography-sqlite-example
   ```
4. **Run Application**: Compile and run the Rust application.
   ```sh
   cargo run
   ```

### Request Example
None (This section describes command-line operations for setup).

### Response
None (This section describes command-line operations for setup).
```

--------------------------------

### Install Seaography and SeaORM CLI Tools

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/index

Installs the necessary command-line interface tools for SeaORM and Seaography. The SeaORM CLI is used for generating entities, and the Seaography CLI is used for generating GraphQL schemas and resolvers. Ensure you have Cargo installed.

```bash
cargo install sea-orm-cli@^1.1 # used to generate entities
cargo install seaography-cli@^1.1
```

--------------------------------

### Generate Seaography GraphQL Schema and Run Server

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/source/README

Generates the Seaography GraphQL schema from SeaORM entities and a database connection string, then starts the GraphQL server. This command requires the path to entities, database URL, and a name for the generated schema.

```sh
seaography-cli ./ src/entities mysql://user:pw@127.0.0.1/sakila seaography-mysql-example
cargo run
```

--------------------------------

### SQLite Setup for Seaography with Sea-ORM CLI

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/index

This snippet outlines the process for setting up a SQLite database with Seaography. It includes changing the directory, generating Sea-ORM entities from a Sakila SQLite database, and then using the Seaography CLI to generate SQLite-specific code before running the application.

```bash
cd examples/sqlite
sea-orm-cli generate entity -o src/entities -u sqlite://sakila.db --seaography
seaography-cli ./ src/entities sqlite://sakila.db seaography-sqlite-example
cargo run
```

--------------------------------

### GraphQL Query: Fetch Films and Actors

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/index

An example GraphQL query to fetch a list of films with pagination and ordering by title, including their associated actors. This demonstrates fetching related data and applying basic filtering and pagination arguments.

```graphql
{
  film(pagination: { page: { limit: 10, page: 0 } }, orderBy: { title: ASC }) {
    nodes {
      title
      description
      releaseYear
      actor {
        nodes {
          firstName
          lastName
        }
      }
    }
  }
}
```

--------------------------------

### GraphQL Query: Fetch Store and Employee with Filters

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/index

An example GraphQL query to fetch a store by its ID and retrieve its address and staff information. This demonstrates filtering by a specific field (storeId) and accessing nested relations.

```graphql
{
  store(filters: { storeId: { eq: 1 } }) {
    nodes {
      storeId
      address {
        address
        address2
      }
      staff {
        firstName
        lastName
      }
    }
  }
}
```

--------------------------------

### GraphQL Query: Fetch Inactive Customers with Cursor Pagination

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/index

An example GraphQL query to fetch inactive customers using cursor-based pagination. This demonstrates how to use a cursor to retrieve subsequent pages of results and access page information.

```graphql
{
  customer(
    filters: { active: { eq: 0 } }
    pagination: { cursor: { limit: 3, cursor: "Int[3]:271" } }
  ) {
    nodes {
      customerId
      lastName
      email
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      endCursor
    }
  }
}
```

--------------------------------

### GraphQL Query: Fetch Inactive Customers with Page Pagination

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/index

An example GraphQL query to fetch inactive customers with page-based pagination. It filters customers where 'active' is 0 and retrieves specific customer details along with pagination information.

```graphql
{
  customer(
    filters: { active: { eq: 0 } }
    pagination: { page: { page: 2, limit: 3 } }
  ) {
    nodes {
      customerId
      lastName
      email
    }
    paginationInfo {
      pages
      current
    }
  }
}
```

--------------------------------

### Seaography Cargo.toml Configuration

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/source/Cargo.toml

This Cargo.toml file defines the configuration for the seaography Rust crate. It specifies the package details, dependencies (including async-graphql and sea-orm with specific features), and feature flags. It also includes patch configurations for crates.io repositories.

```toml
[workspace]
members = [".", "cli", "generator"]

[package]
name = "seaography"
version = "2.0.0-rc.1"
edition = "2021"
rust-version = "1.70"
authors = ["Panagiotis Karatakis <panagiotiskaratakis@gmail.com>"]
description = "🌊 A GraphQL framework and code generator for SeaORM"
license = "MIT OR Apache-2.0"
homepage = "https://www.sea-ql.org/Seaography"
documentation = "https://docs.rs/seaography"
repository = "https://github.com/SeaQL/seaography"
keywords = ["async", "graphql", "mysql", "postgres", "sqlite"]
categories = ["database"]

[dependencies]
async-graphql = { version = "7.0", features = ["decimal", "chrono", "dataloader", "dynamic-schema"] }
sea-orm = { version = "~2.0.0-rc", default-features = false, features = ["seaography", "with-json"] }
itertools = { version = "0.12.0" }
heck = { version = "0.4.1" }
thiserror = { version = "1.0.44" }
fnv = { version = "1.0.7" }
lazy_static = { version = "1.5" }
serde_json = { version = "1.0" }

[features]
default = ["field-camel-case"]
with-json = ["sea-orm/with-json"]
with-chrono = ["sea-orm/with-chrono", "async-graphql/chrono"]
with-time = ["sea-orm/with-time", "async-graphql/time"]
with-uuid = ["sea-orm/with-uuid"]
with-decimal = ["sea-orm/with-rust_decimal", "async-graphql/decimal"]
with-bigdecimal = ["sea-orm/with-bigdecimal", "async-graphql/bigdecimal"]
with-postgres-array = ["sea-orm/postgres-array"]
# with-ipnetwork = ["sea-orm/with-ipnetwork"]
# with-mac_address = ["sea-orm/with-mac_address"]
field-snake-case = []
field-camel-case = []

[patch.crates-io]
sea-orm = { git = "https://github.com/SeaQL/sea-orm", branch = "master" }
sea-orm-migration = { git = "https://github.com/SeaQL/sea-orm", branch = "master" }
```

--------------------------------

### Seaography Crate Dependencies

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/source/Cargo

This snippet outlines the dependencies for the seaography crate, including versions and feature flags for libraries like async-graphql, SeaORM, and serde_json. It also details various feature flags that can be enabled to customize functionality.

```toml
[dependencies.async-graphql]
features = ["decimal", "chrono", "dataloader", "dynamic-schema"]
version = "7.0"

[dependencies.fnv]
version = "1.0.7"

[dependencies.heck]
version = "0.4.1"

[dependencies.itertools]
version = "0.12.0"

[dependencies.lazy_static]
version = "1.5"

[dependencies.sea-orm]
default-features = false
features = ["seaography", "with-json"]
version = "~2.0.0-rc"

[dependencies.serde_json]
version = "1.0"

[dependencies.thiserror]
version = "1.0.44"

[features]
default = ["field-camel-case"]
field-camel-case = []
field-snake-case = []
with-bigdecimal = ["sea-orm/with-bigdecimal", "async-graphql/bigdecimal"]
with-chrono = ["sea-orm/with-chrono", "async-graphql/chrono"]
with-decimal = ["sea-orm/with-rust_decimal", "async-graphql/decimal"]
with-json = ["sea-orm/with-json"]
with-postgres-array = ["sea-orm/postgres-array"]
with-time = ["sea-orm/with-time", "async-graphql/time"]
with-uuid = ["sea-orm/with-uuid"]

[lib]
name = "seaography"
path = "src/lib.rs"

[package]
authors = ["Panagiotis Karatakis <panagiotiskaratakis@gmail.com>"]
autobenches = false
autobins = false
autoexamples = false
autolib = false
autotests = false
build = false
categories = ["database"]
description = "🧭 A GraphQL framework and code generator for SeaORM"
documentation = "https://docs.rs/seaography"
edition = "2021"
homepage = "https://www.sea-ql.org/Seaography"
keywords = ["async", "graphql", "mysql", "postgres", "sqlite"]
license = "MIT OR Apache-2.0"
name = "seaography"
readme = "README.md"
repository = "https://github.com/SeaQL/seaography"
rust-version = "1.70"
version = "2.0.0-rc.1"

```

--------------------------------

### Generate SeaORM Entities with Seaography Support (MySQL)

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/index

Generates SeaORM entities from a MySQL database and configures them for use with Seaography. This command connects to the specified database, generates entity files in the 'src/entities' directory, and enables Seaography-specific features.

```bash
cd examples/mysql
sea-orm-cli generate entity -o src/entities -u mysql://user:pw@127.0.0.1/sakila --seaography
seaography-cli ./ src/entities mysql://user:pw@127.0.0.1/sakila seaography-mysql-example
cargo run
```

--------------------------------

### Generate SeaORM Entities with Seaography Flag

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/source/README

Generates SeaORM entities from a MySQL database schema, including the `--seaography` flag to prepare entities for Seaography integration. This command requires the database connection URL and an output directory.

```sh
sea-orm-cli generate entity -o src/entities -u mysql://user:pw@127.0.0.1/sakila --seaography
```

--------------------------------

### EditorConfig Configuration

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/source/.editorconfig

This code snippet defines the EditorConfig settings for a project. It specifies indentation style, size, end-of-line characters, charset, and whitespace trimming rules. These settings help maintain consistent code style across different editors and IDEs.

```editorconfig
# EditorConfig is awesome: https://EditorConfig.org

# top-most EditorConfig file
root = true

[*]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = false
```

--------------------------------

### GraphQL Query: Complex Filters on Relations and Pagination

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/index

A complex GraphQL query that demonstrates filtering customers by 'active' status, nesting address and payment information, applying filters to payments (amount greater than 7), and using both page and cursor pagination within the nested query.

```graphql
{
  customer(
    filters: { active: { eq: 0 } }
    pagination: { cursor: { limit: 3, cursor: "Int[3]:271" } }
  ) {
    nodes {
      customerId
      lastName
      email
      address {
        address
      }
      payment(
        filters: { amount: { gt: "7" } }
        orderBy: { amount: ASC }
        pagination: { page: { limit: 1, page: 1 } }
      ) {
        nodes {
          paymentId
          amount
        }
        paginationInfo {
          pages
          current
        }
        pageInfo {
          hasPreviousPage
          hasNextPage
        }
      }
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      endCursor
    }
  }
}
```

--------------------------------

### Complex Query with Filters on Relations

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/source/README

This endpoint demonstrates a complex GraphQL query to find inactive customers, including their address and payments with an amount greater than 7, ordered by amount. It showcases filtering on relations and pagination.

```APIDOC
## Query customer

### Description
Find all inactive customers, include their address, and their payments with amount greater than 7 ordered by amount the second result.

### Method
POST

### Endpoint
/graphql

### Parameters
#### Query Parameters
None

#### Request Body
- **customer** (object) - Required - The root query object for customer data.
  - **filters** (object) - Optional - Filters to apply to the customer query.
    - **active** (object) - Optional - Filter by active status.
      - **eq** (integer) - Required - Equality filter for active status (0 for inactive).
  - **pagination** (object) - Optional - Pagination for the customer query.
    - **cursor** (object) - Optional - Cursor-based pagination.
      - **limit** (integer) - Optional - Maximum number of results per page.
      - **cursor** (string) - Optional - Cursor for fetching the next page.
  - **nodes** (object) - Required - Fields to retrieve for each customer node.
    - **customerId** (string) - Description not available.
    - **lastName** (string) - Description not available.
    - **email** (string) - Description not available.
    - **address** (object) - Optional - Include customer's address.
      - **address** (string) - Description not available.
    - **payment** (object) - Optional - Include customer's payments.
      - **filters** (object) - Optional - Filters to apply to the payment query.
        - **amount** (object) - Optional - Filter by payment amount.
          - **gt** (string) - Required - Greater than filter for amount.
      - **orderBy** (object) - Optional - Order for the payment query.
        - **amount** (string) - Required - Order by payment amount (ASC for ascending).
      - **pagination** (object) - Optional - Pagination for the payment query.
        - **page** (object) - Optional - Page-based pagination.
          - **limit** (integer) - Optional - Maximum number of results per page.
          - **page** (integer) - Optional - Page number.
      - **nodes** (object) - Required - Fields to retrieve for each payment node.
        - **paymentId** (string) - Description not available.
        - **amount** (string) - Description not available.
      - **paginationInfo** (object) - Optional - Information about payment pagination.
        - **pages** (integer) - Description not available.
        - **current** (integer) - Description not available.
      - **pageInfo** (object) - Optional - Page information for payments.
        - **hasPreviousPage** (boolean) - Description not available.
        - **hasNextPage** (boolean) - Description not available.
  - **pageInfo** (object) - Optional - Page information for customers.
    - **hasPreviousPage** (boolean) - Description not available.
    - **hasNextPage** (boolean) - Description not available.
    - **endCursor** (string) - Description not available.

### Request Example
```json
{
  "query": "{\n  customer(\n    filters: { active: { eq: 0 } }\n    pagination: { cursor: { limit: 3, cursor: \"Int[3]:271\" } }\n  ) {\n    nodes {\n      customerId\n      lastName\n      email\n      address {\n        address\n      }\n      payment(\n        filters: { amount: { gt: \"7\" } }\n        orderBy: { amount: ASC }\n        pagination: { page: { limit: 1, page: 1 } }\n      ) {\n        nodes {\n          paymentId\n          amount\n        }\n        paginationInfo {\n          pages\n          current\n        }\n        pageInfo {\n          hasPreviousPage\n          hasNextPage\n        }\n      }\n    }\n    pageInfo {\n      hasPreviousPage\n      hasNextPage\n      endCursor\n    }\n  }\n}"
}
```

### Response
#### Success Response (200)
- **data** (object) - The response data.
  - **customer** (object) - Customer data.
    - **nodes** (array) - Array of customer nodes.
      - **customerId** (string) - Description not available.
      - **lastName** (string) - Description not available.
      - **email** (string) - Description not available.
      - **address** (object) - Customer address.
        - **address** (string) - Description not available.
      - **payment** (object) - Customer payments.
        - **nodes** (array) - Array of payment nodes.
          - **paymentId** (string) - Description not available.
          - **amount** (string) - Description not available.
        - **paginationInfo** (object) - Payment pagination info.
          - **pages** (integer) - Description not available.
          - **current** (integer) - Description not available.
        - **pageInfo** (object) - Payment page info.
          - **hasPreviousPage** (boolean) - Description not available.
          - **hasNextPage** (boolean) - Description not available.
    - **pageInfo** (object) - Customer page info.
      - **hasPreviousPage** (boolean) - Description not available.
      - **hasNextPage** (boolean) - Description not available.
      - **endCursor** (string) - Description not available.

#### Response Example
```json
{
  "data": {
    "customer": {
      "nodes": [
        {
          "customerId": "1",
          "lastName": "Smith",
          "email": "john.smith@example.com",
          "address": {
            "address": "123 Main St"
          },
          "payment": {
            "nodes": [
              {
                "paymentId": "p1",
                "amount": "10.50"
              }
            ],
            "paginationInfo": {
              "pages": 1,
              "current": 1
            },
            "pageInfo": {
              "hasPreviousPage": false,
              "hasNextPage": false
            }
          }
        }
      ],
      "pageInfo": {
        "hasPreviousPage": false,
        "hasNextPage": true,
        "endCursor": "cursor123"
      }
    }
  }
}
```
```

--------------------------------

### Filter using Enumeration

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/source/README

This endpoint shows how to filter data using an enumeration type. It retrieves films with a specific rating (NC17) and applies pagination.

```APIDOC
## Query film

### Description
Filter using enumeration to find films with a specific rating.

### Method
POST

### Endpoint
/graphql

### Parameters
#### Query Parameters
None

#### Request Body
- **film** (object) - Required - The root query object for film data.
  - **filters** (object) - Optional - Filters to apply to the film query.
    - **rating** (object) - Optional - Filter by film rating.
      - **eq** (string) - Required - Equality filter for rating (e.g., NC17).
  - **pagination** (object) - Optional - Pagination for the film query.
    - **page** (object) - Optional - Page-based pagination.
      - **limit** (integer) - Optional - Maximum number of results per page.
      - **page** (integer) - Optional - Page number.
  - **nodes** (object) - Required - Fields to retrieve for each film node.
    - **filmId** (string) - Description not available.
    - **rating** (string) - Description not available.

### Request Example
```json
{
  "query": "{\n  film(\n    filters: { rating: { eq: NC17 } }\n    pagination: { page: { page: 1, limit: 5 } }\n  ) {\n    nodes {\n      filmId\n      rating\n    }\n  }\n}"
}
```

### Response
#### Success Response (200)
- **data** (object) - The response data.
  - **film** (object) - Film data.
    - **nodes** (array) - Array of film nodes.
      - **filmId** (string) - Description not available.
      - **rating** (string) - Description not available.

#### Response Example
```json
{
  "data": {
    "film": {
      "nodes": [
        {
          "filmId": "f1",
          "rating": "NC17"
        },
        {
          "filmId": "f2",
          "rating": "NC17"
        }
      ]
    }
  }
}
```
```

--------------------------------

### Filter Data with Enum: Seaography GraphQL Query

Source: https://docs.rs/crate/seaography/2.0.0-rc.1/index

This GraphQL query demonstrates how to filter film data using an enumeration for the rating field. It specifies an exact match for the 'NC17' rating and paginates the results to return the first 5 films.

```graphql
{
  film(
    filters: { rating: { eq: NC17 } }
    pagination: { page: { page: 1, limit: 5 } }
  ) {
    nodes {
      filmId
      rating
    }
  }
}
```
Tokens:
Raw