Pattern Matching with Queries

Search and match code patterns using Tree-sitter’s query language

Introduction

Code analysis often requires finding specific patterns in source code. Tree-sitter provides a simple yet powerful pattern-matching language for this purpose, similar to what’s used in its unit test system.

This allows you to express and search for code structures without writing complex parsing logic.

Creating a Query

Create a query by specifying a string containing one or more patterns:

TSQuery *ts_query_new(
  const TSLanguage *language,
  const char *source,
  uint32_t source_len,
  uint32_t *error_offset,
  TSQueryError *error_type
);

language · const TSLanguage* · required

The language that the query is for

source · const char* · required

A string containing one or more S-expression patterns

source_len · uint32_t · required

The length of the source string in bytes

error_offset · uint32_t*

If there’s an error, this will be set to the byte offset of the error

error_type · TSQueryError*

If there’s an error, this will be set to the error type

Error Types

typedef enum {
  TSQueryErrorNone = 0,
  TSQueryErrorSyntax,
  TSQueryErrorNodeType,
  TSQueryErrorField,
  TSQueryErrorCapture,
  TSQueryErrorStructure,
  TSQueryErrorLanguage,
} TSQueryError;

C

#include <tree_sitter/api.h>

const TSLanguage *tree_sitter_javascript(void);

int main() {
  const TSLanguage *language = tree_sitter_javascript();
  
  uint32_t error_offset;
  TSQueryError error_type;
  
  TSQuery *query = ts_query_new(
    language,
    "(function_declaration name: (identifier) @fn-name)",
    strlen("(function_declaration name: (identifier) @fn-name)"),
    &error_offset,
    &error_type
  );
  
  if (!query) {
    fprintf(stderr, "Error at offset %u: %d\n", error_offset, error_type);
    return 1;
  }
  
  // Use the query...
  
  ts_query_delete(query);
  return 0;
}

use tree_sitter::{Query, Language};

let language = tree_sitter_javascript::language();

let query = Query::new(
    &language,
    "(function_declaration name: (identifier) @fn-name)",
).expect("Error creating query");

// Use the query...

const Parser = require('tree-sitter');
const JavaScript = require('tree-sitter-javascript');

const query = new Parser.Query(
  JavaScript,
  '(function_declaration name: (identifier) @fn-name)'
);

// Use the query...

Query Syntax Basics

Queries are written using S-expressions that match the structure of syntax trees:

Simple Pattern

(function_declaration)

Matches all function declarations.

Pattern with Fields

(function_declaration
  name: (identifier) @function-name
  body: (statement_block) @function-body)

Matches function declarations and captures the name and body with labels.

Pattern with Predicates

((identifier) @constant
 (#match? @constant "^[A-Z_]+$"))

Matches identifiers that look like constants (all uppercase).

Executing Queries

Creating a Query Cursor

The TSQuery value is immutable and can be safely shared between threads. To execute the query, create a TSQueryCursor, which carries the state needed for processing:

TSQueryCursor *ts_query_cursor_new(void);

The query cursor should not be shared between threads, but can be reused for many query executions.

Executing the Query

Execute the query on a given syntax node:

void ts_query_cursor_exec(TSQueryCursor *, const TSQuery *, TSNode);

Iterating Over Matches

typedef struct {
  TSNode node;
  uint32_t index;
} TSQueryCapture;

typedef struct {
  uint32_t id;
  uint16_t pattern_index;
  uint16_t capture_count;
  const TSQueryCapture *captures;
} TSQueryMatch;

bool ts_query_cursor_next_match(TSQueryCursor *, TSQueryMatch *match);

This function returns false when there are no more matches. Otherwise, it populates the match with data about which pattern matched and which nodes were captured.

Complete Example

C

#include <stdio.h>
#include <string.h>
#include <tree_sitter/api.h>

const TSLanguage *tree_sitter_javascript(void);

int main() {
  // Setup parser
  TSParser *parser = ts_parser_new();
  ts_parser_set_language(parser, tree_sitter_javascript());
  
  // Parse code
  const char *source_code = "function one() { two(); function three() {} }";
  TSTree *tree = ts_parser_parse_string(
    parser, NULL, source_code, strlen(source_code)
  );
  
  // Create query
  const char *query_string = 
    "(function_declaration name: (identifier) @fn-def)\n"
    "(call_expression function: (identifier) @fn-ref)";
  
  uint32_t error_offset;
  TSQueryError error_type;
  TSQuery *query = ts_query_new(
    tree_sitter_javascript(),
    query_string,
    strlen(query_string),
    &error_offset,
    &error_type
  );
  
  // Execute query
  TSQueryCursor *cursor = ts_query_cursor_new();
  ts_query_cursor_exec(cursor, query, ts_tree_root_node(tree));
  
  // Iterate matches
  TSQueryMatch match;
  while (ts_query_cursor_next_match(cursor, &match)) {
    printf("Match pattern %d:\n", match.pattern_index);
    
    for (uint32_t i = 0; i < match.capture_count; i++) {
      TSQueryCapture capture = match.captures[i];
      uint32_t length;
      const char *name = ts_query_capture_name_for_id(
        query, capture.index, &length
      );
      
      uint32_t start = ts_node_start_byte(capture.node);
      uint32_t end = ts_node_end_byte(capture.node);
      
      printf("  @%.*s: %.*s\n",
             length, name,
             end - start, source_code + start);
    }
  }
  
  // Cleanup
  ts_query_cursor_delete(cursor);
  ts_query_delete(query);
  ts_tree_delete(tree);
  ts_parser_delete(parser);
  return 0;
}

use tree_sitter::{Parser, Query, QueryCursor};

let mut parser = Parser::new();
parser.set_language(&tree_sitter_javascript::language()).unwrap();

// Parse code
let source_code = "function one() { two(); function three() {} }";
let tree = parser.parse(source_code, None).unwrap();

// Create query
let query = Query::new(
    &tree_sitter_javascript::language(),
    r#"
    (function_declaration name: (identifier) @fn-def)
    (call_expression function: (identifier) @fn-ref)
    "#,
).unwrap();

// Execute query
let mut cursor = QueryCursor::new();
let matches = cursor.matches(&query, tree.root_node(), source_code.as_bytes());

// Iterate matches
for match_ in matches {
    println!("Match pattern {}:", match_.pattern_index);
    
    for capture in match_.captures {
        let capture_name = &query.capture_names()[capture.index as usize];
        let text = &source_code[capture.node.byte_range()];
        
        println!("  @{}: {}", capture_name, text);
    }
}

const Parser = require('tree-sitter');
const JavaScript = require('tree-sitter-javascript');

const parser = new Parser();
parser.setLanguage(JavaScript);

// Parse code
const sourceCode = 'function one() { two(); function three() {} }';
const tree = parser.parse(sourceCode);

// Create and execute query
const query = new Parser.Query(
  JavaScript,
  `
  (function_declaration name: (identifier) @fn-def)
  (call_expression function: (identifier) @fn-ref)
  `
);

const matches = query.matches(tree.rootNode);

// Iterate matches
for (const match of matches) {
  console.log(`Match pattern ${match.pattern}:`);
  
  for (const capture of match.captures) {
    const text = sourceCode.substring(
      capture.node.startIndex,
      capture.node.endIndex
    );
    console.log(`  @${capture.name}: ${text}`);
  }
}

Iterating Over Captures

Instead of iterating over complete matches, you can iterate over individual captures in order:

bool ts_query_cursor_next_capture(
  TSQueryCursor *self,
  TSQueryMatch *match,
  uint32_t *capture_index
);

This is useful when you don’t care about which pattern matched and just want a single ordered sequence of captures.

C

TSQueryMatch match;
uint32_t capture_index;

while (ts_query_cursor_next_capture(cursor, &match, &capture_index)) {
  TSQueryCapture capture = match.captures[capture_index];
  uint32_t length;
  const char *name = ts_query_capture_name_for_id(
    query, capture.index, &length
  );
  
  printf("Capture @%.*s\n", length, name);
}

let mut cursor = QueryCursor::new();
let captures = cursor.captures(&query, tree.root_node(), source_code.as_bytes());

for (match_, capture_index) in captures {
    let capture = &match_.captures[capture_index];
    let capture_name = &query.capture_names()[capture.index as usize];
    
    println!("Capture @{}", capture_name);
}

const captures = query.captures(tree.rootNode);

for (const capture of captures) {
  console.log(`Capture @${capture.name}`);
}

Setting Query Ranges

You can limit the range in which queries execute:

bool ts_query_cursor_set_byte_range(
  TSQueryCursor *self,
  uint32_t start_byte,
  uint32_t end_byte
);

bool ts_query_cursor_set_point_range(
  TSQueryCursor *self,
  TSPoint start_point,
  TSPoint end_point
);

C

// Only search within bytes 100-500
ts_query_cursor_set_byte_range(cursor, 100, 500);
ts_query_cursor_exec(cursor, query, ts_tree_root_node(tree));

// Only search within specific point range
cursor.set_point_range(std::ops::Range {
    start: Point { row: 10, column: 0 },
    end: Point { row: 20, column: 0 },
});

// Search in specific range
const matches = query.matches(
  tree.rootNode,
  {
    startPosition: { row: 10, column: 0 },
    endPosition: { row: 20, column: 0 }
  }
);

The query cursor will return matches that intersect with the given range. A match may be returned even if some of its captures fall outside the specified range, as long as at least part of the match overlaps with the range.

Query Properties and Predicates

Queries support predicates for filtering matches:

Text Predicates

; Match identifiers equal to "foo"
((identifier) @id (#eq? @id "foo"))

; Match identifiers matching a regex
((identifier) @const (#match? @const "^[A-Z_]+$"))

; Match identifiers NOT equal to "bar"
((identifier) @id (#not-eq? @id "bar"))

Property Settings

; Set properties on matches
((comment) @comment.documentation
 (#match? @comment.documentation "^///"))

Getting Predicate Information

const TSQueryPredicateStep *ts_query_predicates_for_pattern(
  const TSQuery *self,
  uint32_t pattern_index,
  uint32_t *step_count
);

Advanced Query Features

Query Introspection

// Get counts
uint32_t ts_query_pattern_count(const TSQuery *self);
uint32_t ts_query_capture_count(const TSQuery *self);
uint32_t ts_query_string_count(const TSQuery *self);

// Get pattern info
uint32_t ts_query_start_byte_for_pattern(const TSQuery *self, uint32_t pattern_index);
uint32_t ts_query_end_byte_for_pattern(const TSQuery *self, uint32_t pattern_index);

// Check pattern properties
bool ts_query_is_pattern_rooted(const TSQuery *self, uint32_t pattern_index);
bool ts_query_is_pattern_non_local(const TSQuery *self, uint32_t pattern_index);

Disabling Patterns and Captures

void ts_query_disable_capture(TSQuery *self, const char *name, uint32_t length);
void ts_query_disable_pattern(TSQuery *self, uint32_t pattern_index);

This prevents patterns or captures from matching and reduces resource usage.

Match Limits

void ts_query_cursor_set_match_limit(TSQueryCursor *self, uint32_t limit);
uint32_t ts_query_cursor_match_limit(const TSQueryCursor *self);
bool ts_query_cursor_did_exceed_match_limit(const TSQueryCursor *self);

Set a maximum number of in-progress matches to prevent excessive memory usage.

Next Steps

Query Syntax

Learn the complete query syntax

Query Predicates

Master predicates and directives

Static Node Types

Generate type information for queries