enhancement: add filtering to GraphQL API queries

[deekerno]

Closes #637.

Changelog

• Add arguments module to fuel-indexer-schema::db; this is where all functionality for GraphQL query arguments should be located
• Add pub fn parse_arguments(..); this is the entry point for parsing any query args
  -- todo!() stubs have been added for sorting and pagination
• Add functionality and tests for the following filter types:
  -- id: select a record by its ID
  -- and / or: combine two filters together
  -- not: negate the behavior of a filter
  -- has: select records that have non-null values for columns in list
  -- in: select records that have a value matching an element in set
  -- gt / gte / lt / lte (greater than, etc.): select records whose value satisfies the comparison condition
  -- between: select records whose value falls between the bounds of the comparison condition
• Move GraphQL API query to DB query functionality from fuel-indexer-schema/db/lib.rs to fuel-indexer-schema/db/queries.rs
• Add additional variants to GraphQLError

Testing Plan

Added several new tests that check each element in a set of results after filtering as well as ensuring that there are no extra elements that do not satisfy the filter conditions. CI should pass.

Manual Testing

0. Clear your database and ensure that WASM modules are up-to-date.
1. Start the explorer indexer example with the beta-3 testnet:

cargo run --bin fuel-indexer -- run --fuel-node-host beta-3.fuel.network --fuel-node-port 80 --manifest examples/block-explorer/explorer-indexer/explorer_indexer.manifest.yaml

1. Open the playground for the example: http://localhost:29987/api/playground/fuel_examples/explorer_indexer.
2. Run the following query; notice that there are many results (this is the non-filtered example):

query {
  tx {
    id
    timestamp
    value
    hash
    status
    block {
    	id
    	height
    	timestamp
        hash
    }
  }
}

3. Run the following query; ensure that there are three results returned (this example shows multiple filters on one entity [comprised of a complex comparison and simple comparison, which are joined together by a logical operator]).

query {
  tx {
    id
    timestamp
    value
    hash
    status
    block(filter: { height: { between: { min: 10, max: 15 } }, and: { timestamp: { lt: 1678484680 } } } ) {
    	id
    	height
    	timestamp
        hash
    }
  }
}

4. Run the following query; ensure that there are now only two results returned (this example shows that multiple entities can be filtered in the same query [this is also an example for the membership filter]):

query {
  tx(filter: { hash: { in: ["adbf1b802450b4782358ff05661ef784a1c6ed47ad7b0cca645ff8fb75debb26", "9c6db9e9d75c2b357931ff7055af2da612a4017ccfe1af71b70ca88c22c9e2e3"] } } ) {
    id
    timestamp
    value
    hash
    status
    block(filter: { height: { between: { min: 10, max: 15 } }, and: { timestamp: { lt: 1678484680 } } } ) {
    	id
    	height
    	timestamp
        hash
    }
  }
}

Notes

Documentation updates will come in a separate PR so that this one doesn't get even bigger.

This implementation uses a fork of graphql-parser. The original version of the crate does not allow for parsing numbers greater than i64::MAX (as its internal number type is hard-coded to an i64); we allow for storing u64 and u128, so we need to figure out a way to parse u64s and u128s from valid GraphQL queries. As such, I've forked graphql-parser and added the necessary functionality; you can find the fork here and the diff for the changes here; it should be noted that the original crate has not released a new version in quite some time so there should be minimal burden from upstream changes.

[ra0x3]

@deekerno

• Fine to merge into the feature branch
• As mentioned, I don't think we'll be able to really see if it works until we just start using it slash open it up
• Just left comments regarding needing Rust docs and comments, as I think this GraphQL stuff has the most business logic of any part of the codebase (e.g., business logic being something that's not self documenting like everything else).

[ra0x3]

Would it be possible to abstract away some of this raw string usage? E.g.,

struct Join {
  rk_table: String,
  rk_col: String,
  pk_table: String,
  pk_col: String,
  is_the_condition: bool,
}



impl ToString for Join {
  fn to_string(&self) -> String {
    if self.is_the_condition {
        format!("{{}.{} = {}.{}", self.rk_table, self.rk_col, self.pk_table, self.pk_col)
    } else {
      // So on and so forth
    }
  }
}

I think making some of this a bit more Rust-y would make it easier to follow without changing any functionality/logic . Totally fine if not, just thinking how to make it a bit more readable

[ra0x3]

All of this business logic here is gonna need a comment as it's not clear what's going on

[ra0x3]

I don't think this comment helps me understand what this logic is doing

[ra0x3]

It would be helpful when you add rust-doc comments to explain what strategy you're using to parse these query elements. The more info the better

[ra0x3]

When you add rust-docs it'd be nice to know what the overall strategy is here for this to_sql method. The more info the better.

[ra0x3]

Could use a helpful high-level rust doc comment here as well. The more info the better

[deekerno]

Noted on the comments. Look out for a small refactoring/commenting PR to make this clearer.