@gitlab/query-language-rust

中文文档
0.42.0发布于 2026/10/20MITESM + CJS近 30 天下载 16.7万

GLQL transpiler, wrapping the WASM build, written in Rust

原始使用文档
文档目录24 节
  1. npm / WASM
  2. Usage
  3. Running the Browser Playground
  4. Ruby Gem
  5. Installation
  6. Usage
  7. Interactive Console (CLI / REPL)
  8. Development
  9. Setting Up Lefthook
  10. Pre-push Hooks
  11. Running Tests
  12. Rust Tests
  13. WASM Package Tests
  14. Code Coverage
  15. Regenerating the schema
  16. Formatting Code
  17. Linting with Clippy
  18. End-to-End Testing
  19. Contributing
  20. Toolchain version sync
  21. Release process
  22. Additional Reading
  23. Learning Rust
  24. Learning more about GLQL

GitLab Query Language

Latest Release Rust Coverage Pipeline Status

The compiler is built in Rust[^1] and distributed as two packages:

  • npm / WASM (@gitlab/query-language-rust): Used by GitLab's frontend for client-side query compilation.
  • Ruby gem (gitlab_query_language): Used by GitLab's backend for server-side query processing.

Goals of this library include:

  • Transpiling GLQL queries, including the YAML frontmatter block to a GraphQL response.
  • Transforming the result of a GraphQL call using transformer functions.

npm / WASM

@gitlab/query-language-rust is an npm module that provides a simple interface for converting glql queries into other formats.

It wraps the WebAssembly build of the glql compiler, written in Rust.

Usage

Install the module:

npm install --save @gitlab/query-language-rust

Import and use the module:

<script type="module">
  import { glql } from '@gitlab/query-language-rust';

  let query = 'label != "backend" and author = currentUser() and weight = 1 and updated > today()';

  let graphql = await glql.compile(query, {
    group: 'gitlab-org',
    username: 'johnhope',
  });

  console.log(graphql);
</script>

The schema is not exported here. It is served by the Ruby gem instead (Glql.schema, under Ruby Gem below), which is its only consumer today.

Running the Browser Playground

Clone the repo, then install the dev dependencies, build the WASM target, and serve the npm/ directory:

npm install
cargo install wasm-pack
rustup target add wasm32-unknown-unknown
wasm-pack build --target web
npx wds -r npm/

Ruby Gem

The same Rust compiler is also available as a Ruby gem, providing native Ruby bindings for server-side use.

Installation

Add to your Gemfile:

gem 'gitlab_query_language'

Or install directly:

gem install gitlab_query_language

Usage

require 'gitlab_query_language'

query = 'label != "backend" and author = currentUser() and weight = 1'
result = Glql.compile(query, { group: 'gitlab-org', username: 'johnhope', fields: 'title' })
puts result

Glql.schema returns everything GLQL accepts - the data sources, their fields, the operators each field takes, and the available functions:

Glql.schema["sources"].map { |source| source["name"] }
# => ["WorkItems", "MergeRequests", "Pipelines", "Projects", "Jobs", ...]

schema["version"] is the gem's version.

Interactive Console (CLI / REPL)

The Ruby gem provides a quick way to test GLQL queries from the command line without needing a browser:

cd glql_rb
bundle exec rake compile
bundle exec rake console
irb(main):001> Glql.compile('type = Issue', {group: 'gitlab-org', username: 'johnhope', fields: 'id'})
=>
{"fields" => [{"key" => "id", "label" => "ID", "name" => "id"}],
 "output" => "query GLQL(...) { ... }",
 "success" => true,
 "variables" => { ... }}

For full details on the Ruby gem, see glql_rb/README.md.

Development

Install mise (or asdf), then run:

mise install        # installs Rust, Node.js, and Ruby at the versions pinned in .tool-versions
brew install lefthook  # for managing git hooks (see below)

If using VSCode, consider installing the rust-analyzer extension.

Setting Up Lefthook

Lefthook is used to automate certain checks before pushing code to the repository, such as running tests, ensuring code is formatted, and checking for lint warnings.

To install Lefthook globally on MacOS, run:

brew install lefthook

For other platforms or methods to install, see installation docs for Lefthook.

Once lefthook is installed, enable it in your project by running the following command in the root of your repository:

lefthook install

This command will set up Lefthook to manage git hooks for pre-push checks as defined in the lefthook.yml file.

Pre-push Hooks

The following checks will run automatically before you push your code:

  • Tests: Ensures all tests pass using cargo test.
  • Clippy: Runs cargo clippy to check for lint warnings and ensures no warnings are present.
  • Format: Ensures code is formatted properly using cargo fmt --check.
  • Check: Runs cargo check to verify that the code compiles without errors.

Running Tests

Rust Tests

To run the Rust tests manually, use the following command:

cargo test

This will build and run all tests defined in your Rust project.

WASM Package Tests

To run the WASM package tests, use:

npm test

For continuous integration testing:

npm run test:ci

Code Coverage

Coverage reports are automatically generated in CI/CD and published to GitLab Pages at:

  • Rust coverage: https://gitlab-org.gitlab.io/glql/coverage/

Regenerating the schema

src/schema/schema.json is generated from the analyzers, not written by hand. Regenerate it after changing anything an analyzer declares - a field, an operator, a scope, a source:

cargo run --bin generate-schema && npm run lint:prettier:fix

Both halves define the file, so CI runs exactly those two commands and fails on any diff. Run them and check nothing changed to see what CI will say.

Formatting Code

To ensure your code is properly formatted using rustfmt, run:

cargo fmt -- --check

This command checks whether your code adheres to the formatting rules but does not modify any files. To automatically format your code, run:

cargo fmt

Linting with Clippy

To lint your code and catch common mistakes or inefficiencies, run:

cargo clippy -- -D warnings

This will treat all warnings as errors and prevent the code from building if any warnings are found.

End-to-End Testing

When making changes to the GLQL Rust codebase, you can follow these steps to test your modifications end-to-end in GitLab GDK. The frontend (npm/WASM) and backend (Ruby gem) both need to be rebuilt and pointed at your local checkout.

In the glql repo:

  1. Check out the branch you want to test:
    git checkout my-feature-branch
    
  2. Build the WASM package:
    wasm-pack build --target web --out-dir pkg
    
  3. Build the npm package:
    npm install && npm run build
    
  4. Build the Ruby gem:
    cd glql_rb && bundle install && bundle exec rake compile
    cd ..
    
  5. Print the paths you'll need in the next step:
    echo "WASM path: $(pwd)/npm/dist/main.js"
    echo "Ruby gem path: $(pwd)/glql_rb"
    

In the GitLab GDK directory:

  1. Update the import in app/assets/javascripts/glql/core/parser.js and app/assets/javascripts/glql/core/transformer.js:

    // change from
    import { glql } from '@gitlab/query-language-rust';
    
    // to
    import { glql } from 'file:///[WASM_PATH]';
    
  2. Update the gitlab_query_language line in the root Gemfile to point at your local gem:

    gem 'gitlab_query_language', path: '[GEM_PATH]'
    
  3. Reinstall gem dependencies and restart the affected services so both the Rails backend and Vite frontend pick up the local builds:

    bundle install
    gdk stop rails-web vite && rm -rf tmp/cache/vite && gdk start rails-web vite
    

Now you can test your changes in any markdown field by embedding a GLQL query, for example:

```glql
display: table
fields: title, labels, author
query: group = "gitlab-org" and label = "group::knowledge" and user = currentUser()
```

Note: Every time you change the GLQL Rust code, you must rebuild the WASM, npm, and Ruby gem artifacts for the changes to take effect.

Contributing

  1. If you don't already have access, start onboarding by requesting access to the community forks.
  2. Clone the community fork repository.
  3. Create a new feature branch (git checkout -b feature/my-feature).
  4. Commit your changes (git commit -am 'Add new feature').
  5. Push to the branch (git push origin feature/my-feature).
  6. Open an MR.

Toolchain version sync

Runtime versions are pinned in three places that must stay in sync:

FileWhat it controls
.tool-versionsLocal dev environment (mise / asdf)
.gitlab-ci.ymlCI pipeline images and variables (RUST_VERSION, image tags)
.gitlab/duo/agent-config.ymlDuo Developer agent environment

When bumping a Rust, Node.js, or Ruby version, update all three files.

Release process

[!important] Pre-requisites You need Developer permissions in the project.

On the main branch, run any of the below pipeline jobs to create a release:

  • release-patch: Bump patch version and publish to NPM.
  • release-minor: Bump minor version and publish to NPM.
  • release-major: Bump major version and publish to NPM.

The release-* job will additionally create a release MR to also bump the Ruby gem version and dependency. This currently requires manual approval to trigger the gem release.

See the gem glql_rb/README.md for more details on the release process.

Additional Reading

Learning Rust

Learning more about GLQL

[^1]: Originally written in Haskell.

版本与发布记录

@gitlab/query-language-rust 共发布 89 个版本,首次发布于 2024/11/26;过去 12 个月发布了 26 个版本。

版本发布日期距今
0.42.0latest2026/10/2026 天前
0.41.02026/09/261 个月前
0.40.02026/09/241 个月前
0.39.02026/09/221 个月前
0.38.02026/09/181 个月前
0.37.02026/09/162 个月前

关于 @gitlab/query-language-rust 的常见问题

@gitlab/query-language-rust 是什么?

GLQL transpiler, wrapping the WASM build, written in Rust

如何安装 @gitlab/query-language-rust?

在项目目录运行 npm install @gitlab/query-language-rust,或使用 pnpm add / yarn add / bun add。

@gitlab/query-language-rust 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gitlab__query-language-rust 是否存在。

@gitlab/query-language-rust 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gitlab/query-language-rust 可以商用吗?

@gitlab/query-language-rust 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gitlab/query-language-rust 的下载量有多少?

根据 npm 官方下载统计,@gitlab/query-language-rust 在 2026/10/17 – 2026/11/15 这 30 天内被下载 167,469 次,日均约 5,582 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gitlab/query-language-rust 还在维护吗?

最新版本 0.42.0 发布于 2026/10/20(26 天前);至今共发布 89 个版本,其中过去 12 个月发布了 26 个;首次发布于 2024/11/26。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。