filter.rs

Overview

This file defines GraphQL input filter structures and their serialization for querying blocks and their external block references. It provides a flexible interface to specify field-based filtering criteria for blockchain blocks, supporting complex logical combinations with OR conditions.

The filters are designed to generate SQL-like WHERE clauses for querying block data, leveraging optional typed filters such as boolean, integer, float, and string filters. These filters enable clients to build detailed conditional queries for blockchain data retrieval.

Main Structures

ExtBlkRefFilter

Represents filtering options for external block references with the following fields:

This struct supports nested OR conditions allowing for complex filtering logic on external block references.

Usage Example

let ext_filter = ExtBlkRefFilter {
    root_hash: Some(StringFilter { eq: Some("some_hash".into()), ..Default::default() }),
    or: Some(Box::new(ExtBlkRefFilter {
        file_hash: Some(StringFilter { eq: Some("another_hash".into()), ..Default::default() }),
        ..Default::default()
    })),
    ..Default::default()
};

BlockFilter

Represents filtering options for blocks with a comprehensive set of optional filters:

This struct uses field prefixing for prev_ref and prev_alt_ref filters to flatten the nested fields with specific prefixes, enabling clear and distinct query parameterization.

Usage Example

let block_filter = BlockFilter {
    key_block: Some(BooleanFilter { eq: Some(true), ..Default::default() }),
    workchain_id: Some(IntFilter { eq: Some(-1), ..Default::default() }),
    ..Default::default()
};

The above example filters for blocks that are key blocks and belong to workchain ID -1.

Prefixing Macros

Two macros define prefixes for flattening nested filters:

• prefix_prev_ref with prefix "prev_ref_" for prev_ref fields.

• prefix_prev_alt_ref with prefix "prev_alt_ref_" for prev_alt_ref fields.

This prefixing ensures that nested filter fields are serialized with distinct and meaningful field names when flattened, facilitating straightforward querying.

Trait Implementations

WhereOp for BlockFilter

The BlockFilter struct implements the WhereOp trait, which provides functionality to convert the filter into a SQL-like WHERE clause string. This allows easy integration with database querying mechanisms.

Example

The test cases demonstrate converting a BlockFilter instance into a WHERE clause string:

let bf = BlockFilter {
    key_block: Some(BooleanFilter { eq: Some(true), ..Default::default() }),
    workchain_id: Some(IntFilter { eq: Some(-1), ..Default::default() }),
    ..Default::default()
};
assert_eq!(bf.to_where().unwrap(), "WHERE key_block = true AND workchain_id = -1");

Testing

The tests module contains unit tests validating the behavior of BlockFilter filtering and SQL WHERE clause generation:

• test_block_filter_1: Tests filtering by boolean and integer fields.

• test_block_filter_2: Tests empty filter returns no WHERE clause.

• test_block_filter_3: Tests filtering using nested prev_ref.

• test_block_filter_4: Tests combined nested prev_ref and prev_alt_ref filters with OR logic.

These tests demonstrate the correctness of filter construction and serialization to query strings.

Interaction with Other Modules

This file depends on and interacts with:

• Various Opt*Filter types (OptBooleanFilter, OptFloatFilter, OptIntFilter, OptStringFilter) defined in the filter module, which provide typed filtering capabilities.

• The WhereOp trait from the same filter module, enabling conversion of filters to query clauses.

• The async_graphql crate's InputObject derive macro for GraphQL input schema generation.

• The serde crate for serialization support.

• The serde_with::with_prefix macro for prefixing nested fields.

Together, these components enable defining complex, typed, and nested filtering logic for GraphQL queries related to blockchain blocks.

Visual Diagram

classDiagram
class ExtBlkRefFilter {
+end_lt: OptStringFilter
+file_hash: OptStringFilter
+root_hash: OptStringFilter
+seq_no: OptFloatFilter
+or: Option<ExtBlkRefFilter>
}
class BlockFilter {
+id: OptStringFilter
+after_merge: OptBooleanFilter
+after_split: OptBooleanFilter
+flags: OptIntFilter
+gen_utime: OptFloatFilter
+key_block: OptBooleanFilter
+prev_alt_ref: Option<ExtBlkRefFilter>
+prev_ref: Option<ExtBlkRefFilter>
+shard: OptStringFilter
+status: OptIntFilter
+tr_count: OptIntFilter
+workchain_id: OptIntFilter
+or: Option<BlockFilter>
+to_where()
}
BlockFilter --> ExtBlkRefFilter : uses
ExtBlkRefFilter --> ExtBlkRefFilter : nested OR
BlockFilter --> BlockFilter : nested OR