ferrum-orm 0.1.3__tar.gz → 0.1.5__tar.gz

{ferrum_orm-0.1.3 → ferrum_orm-0.1.5}/Cargo.lock

@@ -223,7 +223,7 @@ checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
 
 [[package]]
 name = "ferrum-core"
-version = "0.1.3"
+version = "0.1.5"
 dependencies = [
  "criterion",
  "proptest",
@@ -234,7 +234,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-migrate"
-version = "0.1.3"
+version = "0.1.5"
 dependencies = [
  "ferrum-core",
  "serde",
@@ -243,7 +243,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-pyo3"
-version = "0.1.3"
+version = "0.1.5"
 dependencies = [
  "ferrum-core",
  "ferrum-sql",
@@ -255,7 +255,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-sql"
-version = "0.1.3"
+version = "0.1.5"
 dependencies = [
  "criterion",
  "ferrum-core",

{ferrum_orm-0.1.3 → ferrum_orm-0.1.5}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/ferrum-core", "crates/ferrum-sql", "crates/ferrum-pyo3"]
 resolver = "2"
 
 [workspace.package]
-version = "0.1.3"
+version = "0.1.5"
 edition = "2021"
 authors = ["Ferrum Contributors"]
 license = "Apache-2.0"

{ferrum_orm-0.1.3 → ferrum_orm-0.1.5}/PKG-INFO

@@ -1,14 +1,16 @@
 Metadata-Version: 2.4
 Name: ferrum-orm
-Version: 0.1.3
+Version: 0.1.5
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Rust
 Classifier: Topic :: Database
 Classifier: Topic :: Software Development :: Libraries
@@ -34,6 +36,7 @@ Requires-Dist: ty>=0.0.49 ; extra == 'dev'
 Requires-Dist: import-linter>=2 ; extra == 'dev'
 Requires-Dist: testcontainers[postgres]>=4 ; extra == 'dev'
 Requires-Dist: pip-audit>=2 ; extra == 'dev'
+Requires-Dist: fastapi>=0.110 ; extra == 'dev'
 Requires-Dist: python-dotenv>=1.0 ; extra == 'dotenv'
 Requires-Dist: msgpack>=1.0 ; extra == 'msgpack'
 Requires-Dist: aioodbc>=0.5 ; extra == 'mssql'
@@ -56,14 +59,16 @@ Provides-Extra: sqlite
 Provides-Extra: uuid7
 License-File: LICENSE
 Summary: Next-generation async ORM for Python with a Rust-powered core
-Keywords: orm,async,postgresql,mysql,sqlite,mssql,pydantic,rust
+Keywords: orm,async,postgresql,mysql,sqlite,mssql,pydantic,rust,asyncpg,query-builder
+Author: Ferrum Contributors
 License: Apache-2.0
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
-Project-URL: Bug Tracker, https://github.com/ferrumdb/ferrum/issues
-Project-URL: Documentation, https://ferrumdb.github.io/ferrum
-Project-URL: Homepage, https://github.com/ferrumdb/ferrum
-Project-URL: Repository, https://github.com/ferrumdb/ferrum
+Project-URL: Changelog, https://github.com/ferrum-orm/ferrum/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/ferrum-orm/ferrum/tree/main/docs
+Project-URL: Homepage, https://github.com/ferrum-orm/ferrum
+Project-URL: Issues, https://github.com/ferrum-orm/ferrum/issues
+Project-URL: Repository, https://github.com/ferrum-orm/ferrum
 
 # Ferrum
 
@@ -180,6 +185,50 @@ Performance-critical components are implemented in Rust:
 
 This allows Ferrum to maintain a Pythonic API without sacrificing performance.
 
+### Cross-Driver Full-Text Search
+
+Native full-text search across PostgreSQL, MySQL, SQLite FTS5, and SQL Server — one
+QuerySet API, dialect-specific SQL emit and migration DDL.
+
+**Query modes** (filter lookups and ranking):
+
+| Mode        | Lookup operator   | Typical use                          |
+| ----------- | ----------------- | ------------------------------------ |
+| `plain`     | `__match`         | Natural-language terms               |
+| `phrase`    | `__match_phrase`  | Exact phrase                         |
+| `websearch` | `__match_websearch` | Web-style quotes, `-` negation   |
+| `boolean`   | `__match_boolean` | Boolean operators (`&`, `\|`, `!`) |
+
+**Convenience methods:**
+
+```python
+# Filter + relevance ranking in one call
+hits = await Article.objects.search(
+    "python async orm", field="body", mode="websearch"
+).limit(10).all(conn)
+
+# Rank without an implicit filter
+ranked = await Article.objects.rank_by("body", "rust", mode="plain").all(conn)
+```
+
+**Index declaration** — PostgreSQL uses `TSVector` columns; other drivers index base
+`text` columns via `Meta.full_text_indexes`:
+
+```python
+from ferrum.models import Field, FullTextIndex
+
+class Article(Model):
+    search_vector: Annotated[TSVector, Field(fts_config="english")] | None = None
+    body: str = ""
+
+    class Meta:
+        full_text_indexes = [FullTextIndex(fields=("body",), config="english")]
+```
+
+Query strings are always bound parameters; `fts_config` and index names come from
+model-metadata allowlists only. See [Getting Started → Vector and full-text columns](docs/getting-started.md)
+and [API Reference](docs/api-reference.md) for per-dialect DDL and operator mapping.
+
 ## Architecture
 
 ```text
@@ -220,7 +269,7 @@ This allows Ferrum to maintain a Pythonic API without sacrificing performance.
 - [x] Migrations (schema diff, apply, revert, CLI)
 - [x] Relationships (ForeignKey, OneToOne, ManyToMany)
 - [x] pgvector KNN search and HNSW/IVFFLAT index DDL
-- [x] Full-text search (TSVector / `plainto_tsquery`)
+- [x] Full-text search (cross-dialect: PostgreSQL, MySQL, SQLite FTS5, SQL Server)
 - [x] Observability hooks (Tier A/B/C)
 - [x] CLI (`makemigrations`, `migrate`, `revert`, `showmigrations`, `inspectdb`, `resetdb`)
 

{ferrum_orm-0.1.3 → ferrum_orm-0.1.5}/README.md

@@ -113,6 +113,50 @@ Performance-critical components are implemented in Rust:
 
 This allows Ferrum to maintain a Pythonic API without sacrificing performance.
 
+### Cross-Driver Full-Text Search
+
+Native full-text search across PostgreSQL, MySQL, SQLite FTS5, and SQL Server — one
+QuerySet API, dialect-specific SQL emit and migration DDL.
+
+**Query modes** (filter lookups and ranking):
+
+| Mode        | Lookup operator   | Typical use                          |
+| ----------- | ----------------- | ------------------------------------ |
+| `plain`     | `__match`         | Natural-language terms               |
+| `phrase`    | `__match_phrase`  | Exact phrase                         |
+| `websearch` | `__match_websearch` | Web-style quotes, `-` negation   |
+| `boolean`   | `__match_boolean` | Boolean operators (`&`, `\|`, `!`) |
+
+**Convenience methods:**
+
+```python
+# Filter + relevance ranking in one call
+hits = await Article.objects.search(
+    "python async orm", field="body", mode="websearch"
+).limit(10).all(conn)
+
+# Rank without an implicit filter
+ranked = await Article.objects.rank_by("body", "rust", mode="plain").all(conn)
+```
+
+**Index declaration** — PostgreSQL uses `TSVector` columns; other drivers index base
+`text` columns via `Meta.full_text_indexes`:
+
+```python
+from ferrum.models import Field, FullTextIndex
+
+class Article(Model):
+    search_vector: Annotated[TSVector, Field(fts_config="english")] | None = None
+    body: str = ""
+
+    class Meta:
+        full_text_indexes = [FullTextIndex(fields=("body",), config="english")]
+```
+
+Query strings are always bound parameters; `fts_config` and index names come from
+model-metadata allowlists only. See [Getting Started → Vector and full-text columns](docs/getting-started.md)
+and [API Reference](docs/api-reference.md) for per-dialect DDL and operator mapping.
+
 ## Architecture
 
 ```text
@@ -153,7 +197,7 @@ This allows Ferrum to maintain a Pythonic API without sacrificing performance.
 - [x] Migrations (schema diff, apply, revert, CLI)
 - [x] Relationships (ForeignKey, OneToOne, ManyToMany)
 - [x] pgvector KNN search and HNSW/IVFFLAT index DDL
-- [x] Full-text search (TSVector / `plainto_tsquery`)
+- [x] Full-text search (cross-dialect: PostgreSQL, MySQL, SQLite FTS5, SQL Server)
 - [x] Observability hooks (Tier A/B/C)
 - [x] CLI (`makemigrations`, `migrate`, `revert`, `showmigrations`, `inspectdb`, `resetdb`)
 

{ferrum_orm-0.1.3 → ferrum_orm-0.1.5}/crates/ferrum-core/benches/hydrate.rs

@@ -20,6 +20,8 @@ fn bench_metadata() -> ModelMetadata {
                 allowed_operators: vec!["eq".into()],
                 nullable: false,
                 vector_dimensions: None,
+                fts_config: None,
+                fts_source_columns: None,
             },
             FieldMeta {
                 name: "title".into(),
@@ -28,6 +30,8 @@ fn bench_metadata() -> ModelMetadata {
                 allowed_operators: vec!["eq".into(), "icontains".into()],
                 nullable: false,
                 vector_dimensions: None,
+                fts_config: None,
+                fts_source_columns: None,
             },
             FieldMeta {
                 name: "body".into(),
@@ -36,6 +40,8 @@ fn bench_metadata() -> ModelMetadata {
                 allowed_operators: vec!["eq".into()],
                 nullable: true,
                 vector_dimensions: None,
+                fts_config: None,
+                fts_source_columns: None,
             },
             FieldMeta {
                 name: "published".into(),
@@ -44,10 +50,13 @@ fn bench_metadata() -> ModelMetadata {
                 allowed_operators: vec!["eq".into()],
                 nullable: false,
                 vector_dimensions: None,
+                fts_config: None,
+                fts_source_columns: None,
             },
         ],
         pk_index: 0,
         pk_fields: vec![0],
+        full_text_indexes: vec![],
     }
 }
 

{ferrum_orm-0.1.3 → ferrum_orm-0.1.5}/crates/ferrum-core/src/compile/mod.rs

@@ -139,6 +139,7 @@ pub fn compile(metadata: &ModelMetadata, ir: &QuerySetIR) -> Result<CompiledQuer
     validate_joins(metadata, ir)?;
     validate_order_by(metadata, ir)?;
     validate_vector_order_by(metadata, ir)?;
+    validate_text_search(metadata, ir)?;
 
     // Validation passed. Return empty CompiledQuery — sql_text and bound_params
     // are populated by the SQL emitter in `ferrum-sql::emit`.
@@ -331,6 +332,147 @@ fn validate_vector_order_by(metadata: &ModelMetadata, ir: &QuerySetIR) -> Result
     Ok(())
 }
 
+/// Ferrum full-text filter operators (validated against ``tsvector`` fields).
+pub const FTS_OPERATORS: &[&str] = &["match", "match_phrase", "match_websearch", "match_boolean"];
+
+fn is_valid_fts_identifier(value: &str) -> bool {
+    !value.is_empty() && value.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
+}
+
+fn validate_fts_field_metadata(
+    field_meta: &crate::ir::metadata::FieldMeta,
+) -> Result<(), CompileError> {
+    if let Some(config) = &field_meta.fts_config {
+        if !is_valid_fts_identifier(config) {
+            return Err(CompileError::MalformedIr {
+                reason: format!("invalid fts_config identifier: {config:?}"),
+            });
+        }
+    }
+    if let Some(cols) = &field_meta.fts_source_columns {
+        for col in cols {
+            if !is_valid_fts_identifier(col) {
+                return Err(CompileError::MalformedIr {
+                    reason: format!("invalid fts_source_columns identifier: {col:?}"),
+                });
+            }
+        }
+    }
+    Ok(())
+}
+
+fn field_supports_fts(
+    metadata: &ModelMetadata,
+    field_meta: &crate::ir::metadata::FieldMeta,
+) -> bool {
+    if field_meta.field_type == FieldType::TsVector {
+        return true;
+    }
+    if field_meta.field_type == FieldType::Text {
+        let in_index = metadata
+            .full_text_indexes
+            .iter()
+            .any(|idx| idx.fields.iter().any(|f| f == &field_meta.name));
+        return in_index || field_meta.fts_source_columns.is_some();
+    }
+    false
+}
+
+fn validate_fts_filter(
+    metadata: &ModelMetadata,
+    filter: &crate::ir::Filter,
+) -> Result<(), CompileError> {
+    let field_meta =
+        metadata
+            .fields
+            .get(filter.field.index)
+            .ok_or_else(|| CompileError::UnknownField {
+                model: metadata.model_name.clone(),
+                field: filter.field.name.clone(),
+            })?;
+    if !field_supports_fts(metadata, field_meta) {
+        return Err(CompileError::UnsupportedOperator {
+            model: metadata.model_name.clone(),
+            field: filter.field.name.clone(),
+            operator: filter.operator.clone(),
+        });
+    }
+    if !matches!(filter.value, BindValue::Text(_)) {
+        return Err(CompileError::MalformedIr {
+            reason: format!(
+                "FTS operator {} requires a text bind value",
+                filter.operator
+            ),
+        });
+    }
+    validate_fts_field_metadata(field_meta)
+}
+
+fn validate_text_rank_by(
+    metadata: &ModelMetadata,
+    rank: &crate::ir::TextRankBy,
+) -> Result<(), CompileError> {
+    let field_meta =
+        metadata
+            .fields
+            .get(rank.field.index)
+            .ok_or_else(|| CompileError::UnknownField {
+                model: metadata.model_name.clone(),
+                field: rank.field.name.clone(),
+            })?;
+    if !field_supports_fts(metadata, field_meta) {
+        return Err(CompileError::UnsupportedOperator {
+            model: metadata.model_name.clone(),
+            field: rank.field.name.clone(),
+            operator: "rank_by".into(),
+        });
+    }
+    if !matches!(rank.query, BindValue::Text(_)) {
+        return Err(CompileError::MalformedIr {
+            reason: "text_rank_by.query must be a text bind value".into(),
+        });
+    }
+    validate_fts_field_metadata(field_meta)?;
+    // Mode is enum-validated at deserialization; no per-query config strings.
+    let _ = rank.mode;
+    Ok(())
+}
+
+fn validate_text_search(metadata: &ModelMetadata, ir: &QuerySetIR) -> Result<(), CompileError> {
+    for filter in &ir.filters {
+        if FTS_OPERATORS.contains(&filter.operator.as_str()) {
+            validate_fts_filter(metadata, filter)?;
+        }
+    }
+    if let Some(predicate) = &ir.predicate {
+        validate_predicate_fts(metadata, predicate)?;
+    }
+    if let Some(rank) = &ir.text_rank_by {
+        validate_text_rank_by(metadata, rank)?;
+    }
+    Ok(())
+}
+
+fn validate_predicate_fts(
+    metadata: &ModelMetadata,
+    predicate: &Predicate,
+) -> Result<(), CompileError> {
+    match predicate {
+        Predicate::And { children } | Predicate::Or { children } => {
+            for child in children {
+                validate_predicate_fts(metadata, child)?;
+            }
+        }
+        Predicate::Not { child } => validate_predicate_fts(metadata, child)?,
+        Predicate::Filter { filter } => {
+            if FTS_OPERATORS.contains(&filter.operator.as_str()) {
+                validate_fts_filter(metadata, filter)?;
+            }
+        }
+    }
+    Ok(())
+}
+
 /// True when the IR carries at least one WHERE constraint (flat filters or a predicate tree).
 #[must_use]
 pub fn ir_has_where_clause(ir: &QuerySetIR) -> bool {
@@ -393,6 +535,8 @@ mod tests {
                     allowed_operators: vec!["eq".into(), "gt".into(), "lt".into()],
                     nullable: false,
                     vector_dimensions: None,
+                    fts_config: None,
+                    fts_source_columns: None,
                 },
                 FieldMeta {
                     name: "email".into(),
@@ -401,10 +545,13 @@ mod tests {
                     allowed_operators: vec!["eq".into(), "icontains".into()],
                     nullable: false,
                     vector_dimensions: None,
+                    fts_config: None,
+                    fts_source_columns: None,
                 },
             ],
             pk_index: 0,
             pk_fields: vec![0],
+            full_text_indexes: vec![],
         }
     }
 
@@ -429,6 +576,7 @@ mod tests {
             limit: None,
             offset: None,
             vector_order_by: None,
+            text_rank_by: None,
             predicate: None,
             distinct: false,
             exists: false,
@@ -520,6 +668,73 @@ mod tests {
         assert_eq!(dir, SortDirection::Unknown);
     }
 
+    #[test]
+    fn rejects_fts_operator_on_non_tsvector_field() {
+        let meta = make_metadata();
+        let mut ir = base_ir("User");
+        ir.filters.push(Filter {
+            field: FieldRef {
+                name: "email".into(),
+                index: 1,
+            },
+            operator: "match".into(),
+            value: BindValue::Text("hello".into()),
+        });
+        let err = compile(&meta, &ir).unwrap_err();
+        assert!(matches!(err, CompileError::UnsupportedOperator { .. }));
+    }
+
+    #[test]
+    fn accepts_tsvector_match_and_text_rank_by() {
+        let meta = ModelMetadata {
+            model_name: "Doc".into(),
+            table_name: "docs".into(),
+            fields: vec![FieldMeta {
+                name: "search_vector".into(),
+                column_name: "search_vector".into(),
+                field_type: FieldType::TsVector,
+                allowed_operators: vec![
+                    "match".into(),
+                    "match_phrase".into(),
+                    "match_websearch".into(),
+                    "match_boolean".into(),
+                    "is_null".into(),
+                ],
+                nullable: true,
+                vector_dimensions: None,
+                fts_config: Some("english".into()),
+                fts_source_columns: None,
+            }],
+            pk_index: 0,
+            pk_fields: vec![0],
+            full_text_indexes: vec![],
+        };
+        let mut ir = base_ir("Doc");
+        ir.operation = Operation::Select {
+            fields: vec![FieldRef {
+                name: "search_vector".into(),
+                index: 0,
+            }],
+        };
+        ir.filters.push(Filter {
+            field: FieldRef {
+                name: "search_vector".into(),
+                index: 0,
+            },
+            operator: "match_phrase".into(),
+            value: BindValue::Text("hello world".into()),
+        });
+        ir.text_rank_by = Some(crate::ir::TextRankBy {
+            field: FieldRef {
+                name: "search_vector".into(),
+                index: 0,
+            },
+            query: BindValue::Text("hello".into()),
+            mode: crate::ir::TextSearchMode::Phrase,
+        });
+        assert!(compile(&meta, &ir).is_ok());
+    }
+
     #[test]
     fn accepts_valid_ir() {
         let meta = make_metadata();
@@ -570,6 +785,7 @@ mod tests {
             limit: None,
             offset: None,
             vector_order_by: None,
+            text_rank_by: None,
             predicate: None,
             distinct: false,
             exists: false,
@@ -598,6 +814,7 @@ mod tests {
             limit: None,
             offset: None,
             vector_order_by: None,
+            text_rank_by: None,
             predicate: None,
             distinct: false,
             exists: false,
@@ -621,6 +838,7 @@ mod tests {
             limit: None,
             offset: None,
             vector_order_by: None,
+            text_rank_by: None,
             predicate: None,
             distinct: false,
             exists: false,
@@ -653,6 +871,7 @@ mod tests {
             limit: None,
             offset: None,
             vector_order_by: None,
+            text_rank_by: None,
             predicate: None,
             distinct: false,
             exists: false,

{ferrum_orm-0.1.3 → ferrum_orm-0.1.5}/crates/ferrum-core/src/hydrate/mod.rs

@@ -89,6 +89,8 @@ mod tests {
                     allowed_operators: vec!["eq".into()],
                     nullable: false,
                     vector_dimensions: None,
+                    fts_config: None,
+                    fts_source_columns: None,
                 },
                 FieldMeta {
                     name: "title".into(),
@@ -97,6 +99,8 @@ mod tests {
                     allowed_operators: vec!["eq".into(), "icontains".into()],
                     nullable: false,
                     vector_dimensions: None,
+                    fts_config: None,
+                    fts_source_columns: None,
                 },
                 FieldMeta {
                     name: "bio".into(),
@@ -105,10 +109,13 @@ mod tests {
                     allowed_operators: vec!["eq".into()],
                     nullable: true, // nullable column
                     vector_dimensions: None,
+                    fts_config: None,
+                    fts_source_columns: None,
                 },
             ],
             pk_index: 0,
             pk_fields: vec![0],
+            full_text_indexes: vec![],
         }
     }
 

{ferrum_orm-0.1.3 → ferrum_orm-0.1.5}/crates/ferrum-core/src/ir/metadata.rs

@@ -29,6 +29,10 @@ pub struct ModelMetadata {
     /// Empty vec is treated as `[pk_index]` for backward compatibility.
     #[serde(default)]
     pub pk_fields: Vec<usize>,
+
+    /// Declarative full-text indexes from model ``Meta.full_text_indexes``.
+    #[serde(default)]
+    pub full_text_indexes: Vec<FullTextIndexMeta>,
 }
 
 /// Metadata for a single model field.
@@ -53,6 +57,27 @@ pub struct FieldMeta {
     /// pgvector dimensionality (DDL-only metadata; optional).
     #[serde(default)]
     pub vector_dimensions: Option<u32>,
+
+    /// `PostgreSQL` text-search configuration (regconfig), e.g. `english`.
+    /// Validated as an allowlisted identifier before SQL emission.
+    #[serde(default)]
+    pub fts_config: Option<String>,
+
+    /// Source columns backing a generated FTS column (MySQL/SQLite/MSSQL).
+    #[serde(default)]
+    pub fts_source_columns: Option<Vec<String>>,
+}
+
+/// Declarative full-text index metadata (``Meta.full_text_indexes``).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct FullTextIndexMeta {
+    /// Index or FTS5 virtual-table name (metadata allowlist).
+    pub name: String,
+    /// Model field names covered by this index.
+    pub fields: Vec<String>,
+    /// Optional language/regconfig identifier (allowlisted).
+    #[serde(default)]
+    pub config: Option<String>,
 }
 
 /// Ferrum-level type tag for a field. Corresponds to Pydantic / Python types.

{ferrum_orm-0.1.3 → ferrum_orm-0.1.5}/crates/ferrum-core/src/ir/mod.rs

@@ -15,7 +15,7 @@ pub mod metadata;
 pub use metadata::ModelMetadata;
 
 /// Version of the IR contract this crate implements.
-pub const IR_VERSION: u32 = 2;
+pub const IR_VERSION: u32 = 3;
 
 /// The root IR node produced by `QuerySet._build_ir()` on the Python side.
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -45,6 +45,10 @@ pub struct QuerySetIR {
     #[serde(default)]
     pub vector_order_by: Option<VectorOrderBy>,
 
+    /// Optional full-text relevance ordering (``QuerySet.rank_by`` / ``QuerySet.search``).
+    #[serde(default)]
+    pub text_rank_by: Option<TextRankBy>,
+
     /// Optional boolean predicate tree (``Q`` objects). When present, combined with
     /// ``filters`` (AND). When absent, ``filters`` are AND-ed as in IR v1.
     #[serde(default)]
@@ -232,6 +236,28 @@ pub struct VectorOrderBy {
     pub value: BindValue,
 }
 
+/// Full-text query parsing mode for ``match_*`` filters and ``text_rank_by``.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum TextSearchMode {
+    /// Natural-language / plain terms (``plainto_tsquery``, ``FREETEXT``, etc.).
+    Plain,
+    /// Exact phrase (``phraseto_tsquery``, phrase mode).
+    Phrase,
+    /// Web-style search syntax (``websearch_to_tsquery``).
+    Websearch,
+    /// Boolean / prefix query DSL (``to_tsquery``, ``IN BOOLEAN MODE``).
+    Boolean,
+}
+
+/// Full-text relevance ordering (``ORDER BY <rank> DESC``).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TextRankBy {
+    pub field: FieldRef,
+    pub query: BindValue,
+    pub mode: TextSearchMode,
+}
+
 /// Sort direction — only `Asc` and `Desc` are valid; anything else deserialized
 /// from Python/JSON becomes `Unknown`, which the compiler rejects with
 /// `CompileError::InvalidSortDirection` before any SQL is produced.