Struct QueryDefinition 

pub struct QueryDefinition {

    pub name: String,
    pub return_type: String,
    pub returns_list: bool,
    pub nullable: bool,
    pub arguments: Vec<ArgumentDefinition>,
    pub sql_source: Option<String>,
    pub description: Option<String>,
    pub auto_params: AutoParams,
    pub deprecation: Option<DeprecationInfo>,
    pub jsonb_column: String,
    pub relay: bool,
    pub relay_cursor_column: Option<String>,
    pub relay_cursor_type: CursorType,
    pub inject_params: IndexMap<String, InjectedParamSource>,
    pub cache_ttl_seconds: Option<u64>,
    pub additional_views: Vec<String>,
    pub requires_role: Option<String>,
    pub rest_path: Option<String>,
    pub rest_method: Option<String>,
}

A query definition compiled from @fraiseql.query.

Queries are declarative bindings to database views/tables. They describe what to fetch, not how to fetch it.

Example

use fraiseql_core::schema::QueryDefinition;

let query = QueryDefinition::new("users", "User");

Fields

name: String

Query name (e.g., “users”).

return_type: String

Return type name (e.g., “User”).

returns_list: bool

Does this query return a list?

nullable: bool

Is the return value nullable?

arguments: Vec<ArgumentDefinition>

Query arguments.

sql_source: Option<String>

SQL source table/view (for direct table queries).

description: Option<String>

Description.

auto_params: AutoParams

Auto-wired parameters (where, orderBy, limit, offset).

deprecation: Option<DeprecationInfo>

Deprecation information (from @deprecated directive). When set, this query is marked as deprecated in the schema.

jsonb_column: String

JSONB column name (e.g., “data”). Used to extract data from JSONB columns in query results.

relay: bool

Whether this query is a Relay connection query.

When true, the compiler wraps the result in XxxConnection with edges { cursor node { ... } } and pageInfo fields, using keyset pagination on pk_{snake_case(return_type)} (BIGINT).

relay_cursor_column: Option<String>

Keyset pagination column for relay queries.

Derived from the return type name: User → pk_user. This BIGINT column lives in the view (sql_source) and is used as the stable sort key for cursor-based keyset pagination:

• Forward: WHERE {col} > $cursor ORDER BY {col} ASC LIMIT $first
• Backward: WHERE {col} < $cursor ORDER BY {col} DESC LIMIT $last

Only set when relay = true.

relay_cursor_type: CursorType

Type of the keyset cursor column.

Defaults to Int64 for backward compatibility with schemas that use pk_{type} BIGINT columns. Set to Uuid when the cursor column has a UUID type.

Only meaningful when relay = true.

inject_params: IndexMap<String, InjectedParamSource>

Server-side parameters injected from JWT claims at runtime.

Keys are SQL column names. Values describe where to source the runtime value. These params are NOT exposed as GraphQL arguments.

For queries: adds a WHERE key = $value condition per entry using the same WhereClause mechanism as TenantEnforcer. Works on all adapters.

Clients cannot override these values.

cache_ttl_seconds: Option<u64>

Per-query result cache TTL in seconds.

Overrides the global CacheConfig::ttl_seconds for this query’s view. Common use-cases:

• Reference data (countries, currencies): 3600 (1 h)
• Live / real-time data: 0 (bypass cache entirely)

None → use the global cache TTL.

additional_views: Vec<String>

Additional database views this query reads beyond the primary sql_source.

When this query JOINs or queries multiple views, list all secondary views here so that mutations touching those views correctly invalidate this query’s cache entries.

Without this list, only sql_source is registered for invalidation. Any mutation that modifies a secondary view will NOT invalidate this query’s cache — silently serving stale data.

Each entry must be a valid SQL identifier (letters, digits, _) validated by the CLI compiler at schema compile time.

Example

@fraiseql.query(
    sql_source="v_user_with_posts",
    additional_views=["v_post"],
)
def users_with_posts() -> list[UserWithPosts]: ...

requires_role: Option<String>

Role required to execute this query and see it in introspection.

When set, only users with this role can discover and execute this query. Users without the role receive "Unknown query" (not FORBIDDEN) to prevent role enumeration.

rest_path: Option<String>

Custom REST path override (e.g., "/users/{id}/posts").

rest_method: Option<String>

REST HTTP method override (e.g., "GET").

Implementations

impl QueryDefinition

pub fn new(name: impl Into<String>, return_type: impl Into<String>) -> Self

Create a new query definition.

pub const fn returning_list(self) -> Self

Set this query to return a list.

pub fn with_sql_source(self, source: impl Into<String>) -> Self

Set the SQL source.

pub fn deprecated(self, reason: Option<String>) -> Self

Mark this query as deprecated.

Example

use fraiseql_core::schema::QueryDefinition;

let query = QueryDefinition::new("oldUsers", "User")
    .deprecated(Some("Use 'users' instead".to_string()));
assert!(query.is_deprecated());

pub const fn is_deprecated(&self) -> bool

Check if this query is deprecated.

pub fn deprecation_reason(&self) -> Option<&str>

Get the deprecation reason if deprecated.

Trait Implementations

impl Clone for QueryDefinition

fn clone(&self) -> QueryDefinition

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for QueryDefinition

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for QueryDefinition

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for QueryDefinition

fn eq(&self, other: &QueryDefinition) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for QueryDefinition

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for QueryDefinition