Developing Rules¶

Rules in SQLFluff are implemented as crawlers. These are entities which work their way through the parsed structure of a query to evaluate a particular rule or set of rules. The intent is that the definition of each specific rule should be really streamlined and only contain the logic for the rule itself, with all the other mechanics abstracted away.

Functional API¶

These newer modules provide a higher-level API for rules working with segments and slices. Rules that need to navigate or search the parse tree may benefit from using these. Eventually, the plan is for all rules to use these modules. As of December 30, 2021, 17+ rules use these modules.

The modules listed below are submodules of sqlfluff.core.rules.functional.

segments Module¶

Surrogate class for working with Segment collections.

class Segments(*segments, templated_file=None)¶

Encapsulates a sequence of one or more BaseSegments.

The segments may or may not be contiguous in a parse tree. Provides useful operations on a sequence of segments to simplify rule creation.

all(predicate: Optional[Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]] = None) → bool¶: Do all the segments match?

any(predicate: Optional[Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]] = None) → bool¶: Do any of the segments match?

apply(fn: Callable[[sqlfluff.core.parser.segments.base.BaseSegment], Any]) → List[Any]¶: Apply function to every item.

children(predicate: Optional[Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]] = None) → sqlfluff.core.rules.functional.segments.Segments¶: Returns an object with children of the segments in this object.

find(segment: Optional[sqlfluff.core.parser.segments.base.BaseSegment]) → int¶: Returns index if found, -1 if not found.

first(predicate: Optional[Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]] = None) → sqlfluff.core.rules.functional.segments.Segments¶: Returns the first segment (if any) that satisfies the predicates.

get(index: int = 0, *, default: Optional[Any] = None) → Optional[sqlfluff.core.parser.segments.base.BaseSegment]¶: Return specified item. Returns default if index out of range.

last(predicate: Optional[Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]] = None) → sqlfluff.core.rules.functional.segments.Segments¶: Returns the last segment (if any) that satisfies the predicates.

property raw_segments: sqlfluff.core.rules.functional.segments.Segments¶: Get raw segments underlying the segments.

property raw_slices: sqlfluff.core.rules.functional.raw_file_slices.RawFileSlices¶: Raw slices of the segments, sorted in source file order.

recursive_crawl(*seg_type: str, recurse_into: bool = True) → sqlfluff.core.rules.functional.segments.Segments¶: Recursively crawl for segments of a given type.

reversed() → sqlfluff.core.rules.functional.segments.Segments¶: Return the same segments in reverse order.

select(select_if: Optional[Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]] = None, loop_while: Optional[Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]] = None, start_seg: Optional[sqlfluff.core.parser.segments.base.BaseSegment] = None, stop_seg: Optional[sqlfluff.core.parser.segments.base.BaseSegment] = None) → sqlfluff.core.rules.functional.segments.Segments¶

Retrieve range/subset.

NOTE: Iterates the segments BETWEEN start_seg and stop_seg, i.e. those segments are not included in the loop.

segment_predicates Module¶

Defines commonly used segment predicates for rule writers.

For consistency, all the predicates in this module are implemented as functions returning functions. This avoids rule writers having to remember the distinction between normal functions and functions returning functions.

This is not necessarily a complete set of predicates covering all possible requirements. Rule authors can define their own predicates as needed, either as regular functions, lambda, etc.

and_(*functions: Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]) → Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]¶: Returns a function that computes the functions and-ed together.

get_name() → Callable[[sqlfluff.core.parser.segments.base.BaseSegment], str]¶: Returns a function that gets segment name.

get_type() → Callable[[sqlfluff.core.parser.segments.base.BaseSegment], str]¶: Returns a function that gets segment type.

is_code() → Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]¶: Returns a function that checks if segment is code.

is_comment() → Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]¶: Returns a function that checks if segment is comment.

is_expandable() → Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]¶: Returns a function that checks if segment is expandable.

is_keyword(*keyword_name) → Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]¶: Returns a function that determines if it’s a matching keyword.

is_meta() → Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]¶: Returns a function that checks if segment is meta.

is_name(*seg_name: str) → Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]¶: Returns a function that determines if segment is one of the names.

is_raw() → Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]¶: Returns a function that checks if segment is raw.

is_type(*seg_type: str) → Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]¶: Returns a function that determines if segment is one of the types.

is_whitespace() → Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]¶: Returns a function that checks if segment is whitespace.

not_(fn: Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]) → Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]¶: Returns a function that computes: not fn().

or_(*functions: Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]) → Callable[[sqlfluff.core.parser.segments.base.BaseSegment], bool]¶: Returns a function that computes the functions or-ed together.

raw_slice(segment: sqlfluff.core.parser.segments.base.BaseSegment, raw_slice_: sqlfluff.core.templaters.base.RawFileSlice) → str¶: Return the portion of a segment’s source provided by raw_slice.

raw_slices(segment: sqlfluff.core.parser.segments.base.BaseSegment, templated_file: Optional[sqlfluff.core.templaters.base.TemplatedFile]) → sqlfluff.core.rules.functional.raw_file_slices.RawFileSlices¶: Returns raw slices for a segment.

templated_slices(segment: sqlfluff.core.parser.segments.base.BaseSegment, templated_file: Optional[sqlfluff.core.templaters.base.TemplatedFile]) → sqlfluff.core.rules.functional.templated_file_slices.TemplatedFileSlices¶: Returns raw slices for a segment.

raw_file_slices Module¶

Surrogate class for working with RawFileSlice collections.

class RawFileSlices(*raw_slices, templated_file=None)¶

Encapsulates a sequence of one or more RawFileSlice.

The slices may or may not be contiguous in a file. Provides useful operations on a sequence of slices to simplify rule creation.

all(predicate: Optional[Callable[[sqlfluff.core.templaters.base.RawFileSlice], bool]] = None) → bool¶: Do all the raw slices match?

any(predicate: Optional[Callable[[sqlfluff.core.templaters.base.RawFileSlice], bool]] = None) → bool¶: Do any of the raw slices match?

select(select_if: Optional[Callable[[sqlfluff.core.templaters.base.RawFileSlice], bool]] = None, loop_while: Optional[Callable[[sqlfluff.core.templaters.base.RawFileSlice], bool]] = None, start_slice: Optional[sqlfluff.core.templaters.base.RawFileSlice] = None, stop_slice: Optional[sqlfluff.core.templaters.base.RawFileSlice] = None) → sqlfluff.core.rules.functional.raw_file_slices.RawFileSlices¶

Retrieve range/subset.

NOTE: Iterates the slices BETWEEN start_slice and stop_slice, i.e. those slices are not included in the loop.

raw_file_slice_predicates Module¶

Defines commonly used raw file slice predicates for rule writers.