API Reference

SQLFluff exposes a public api for other python applications to use. A basic example of this usage is given here, with the documentation for each of the methods below.

"""This is an example of how to use the simple sqlfluff api."""

import sqlfluff

#  -------- LINTING ----------

my_bad_query = "SeLEct  *, 1, blah as  fOO  from myTable"

# Lint the given string and get a list of violations found.
result = sqlfluff.lint(my_bad_query, dialect="bigquery")

# result =
# [
#     {"code": "L010", "line_no": 1, "line_pos": 1, "description": "Inconsistent capitalisation of keywords."}
#     ...
# ]

#  -------- FIXING ----------

# Fix the given string and get a string back which has been fixed.
result = sqlfluff.fix(my_bad_query, dialect="bigquery")
# result = 'SELECT  *, 1, blah AS  foo  FROM mytable\n'

# We can also fix just specific rules.
result = sqlfluff.fix(my_bad_query, rules="L010")
# result = 'SELECT  *, 1, blah AS  fOO  FROM myTable'

# Or a subset of rules...
result = sqlfluff.fix(my_bad_query, rules=["L010", "L014"])
# result = 'SELECT  *, 1, blah AS  fOO  FROM mytable'

#  -------- PARSING ----------
# NOTE: sqlfluff is still in a relatively early phase of its
# development and so until version 1.0.0 will offer no guarantee
# that the names and structure of the objects returned by these
# parse commands won't change between releases. Use with care
# and keep updated with the changelog for the project for any
# changes in this space.

parsed = sqlfluff.parse(my_bad_query)

# Get the structure of the query
structure = parsed.tree.to_tuple(show_raw=True, code_only=True)
# structure = ('file', (('statement', (('select_statement', (('select_clause', (('keyword', 'SeLEct'), ...

# Extract certain elements
keywords = [keyword.raw for keyword in parsed.tree.recursive_crawl("keyword")]
# keywords = ['SeLEct', 'as', 'from']
tbl_refs = [tbl_ref.raw for tbl_ref in parsed.tree.recursive_crawl("table_reference")]
# tbl_refs == ["myTable"]

Simple API commands

Sqlfluff is a SQL linter for humans.

fix(sql, dialect='ansi', rules=None)

Fix a sql string or file.

Parameters
  • sql (str or file-like object) – The sql to be linted either as a string or a subclass of TextIOBase.

  • dialect (str, optional) – A reference to the dialect of the sql to be linted. Defaults to ansi.

  • rules (str or iterable of str, optional) – A subset of rule reference to lint for.

Returns

str for the fixed sql if possible.

lint(sql, dialect='ansi', rules=None)

Lint a sql string or file.

Parameters
  • sql (str or file-like object) – The sql to be linted either as a string or a subclass of TextIOBase.

  • dialect (str, optional) – A reference to the dialect of the sql to be linted. Defaults to ansi.

  • rules (str or iterable of str, optional) – A subset of rule reference to lint for.

Returns

list of dict for each violation found.

parse(sql, dialect='ansi')

Parse a sql string or file.

Parameters
  • sql (str or file-like object) – The sql to be linted either as a string or a subclass of TextIOBase.

  • dialect (str, optional) – A reference to the dialect of the sql to be linted. Defaults to ansi.

Returns

ParsedString containing the parsed structure.

Advanced API usage

The simple API presents only a fraction of the functionality present within the core SQLFluff library. For more advanced use cases, users can import the Linter() and FluffConfig() classes from sqlfluff.core. As of version 0.4.0 this is considered as experimental only as the internals may change without warning in any future release. If you come to rely on the internals of SQLFluff, please post an issue on github to share what you’re up to. This will help shape a more reliable, tidy and well documented public API for use.

The core elements of sqlfluff.

class FluffConfig(configs: Optional[dict] = None, overrides: Optional[dict] = None)

.The class that actually gets passed around as a config object.

diff_to(other: sqlfluff.core.config.FluffConfig)dict

Compare this config to another.

Parameters

other (FluffConfig) – Another config object to compare against. We will return keys from this object that are not in other or are different to those in other.

Returns

A filtered dict of items in this config that are not in the other or are different to the other.

classmethod from_kwargs(config: Optional[sqlfluff.core.config.FluffConfig] = None, dialect: Optional[str] = None, rules: Optional[Union[str, List[str]]] = None)sqlfluff.core.config.FluffConfig

Instantiate a config from either an existing config or kwargs.

This is a convenience method for the ways that the public classes like Linter(), Parser() and Lexer() can be instantiated with a FluffConfig or with the convenience kwargs: dialect & rules.

classmethod from_path(path: str, overrides: Optional[dict] = None)sqlfluff.core.config.FluffConfig

Loads a config object given a particular path.

classmethod from_root(overrides: Optional[dict] = None)sqlfluff.core.config.FluffConfig

Loads a config object just based on the root directory.

get(val: str, section: Union[str, Iterable[str]] = 'core', default: Optional[Any] = None)

Get a particular value from the config.

get_section(section: Union[str, Iterable[str]])Optional[dict]

Return a whole section of config as a dict.

If the element found at the address is a value and not a section, it is still returned and so this can be used as a more advanced from of the basic get method.

Parameters

section – An iterable or string. If it’s a string we load that root section. If it’s an iterable of strings, then we treat it as a path within the dictionary structure.

iter_vals(cfg: Optional[dict] = None)Iterable[tuple]

Return an iterable of tuples representing keys.

We show values before dicts, the tuple contains an indent value to know what level of the dict we’re in. Dict labels will be returned as a blank value before their content.

make_child_from_path(path: str)sqlfluff.core.config.FluffConfig

Make a new child config at a path but pass on overrides.

process_inline_config(config_line: str)

Process an inline config command and update self.

process_raw_file_for_config(raw_str: str)

Process a full raw file for inline config and update self.

set_value(config_path: Iterable[str], val: Any)

Set a value at a given path.

class Lexer(config: Optional[sqlfluff.core.config.FluffConfig] = None, last_resort_lexer: Optional[sqlfluff.core.parser.lexer.StringLexer] = None, dialect: Optional[str] = None)

The Lexer class actually does the lexing step.

elements_to_segments(elements: List[sqlfluff.core.parser.lexer.TemplateElement], templated_file: sqlfluff.core.templaters.base.TemplatedFile)Tuple[sqlfluff.core.parser.segments.raw.RawSegment, ...]

Convert a tuple of lexed elements into a tuple of segments.

lex(raw: Union[str, sqlfluff.core.templaters.base.TemplatedFile])Tuple[Tuple[sqlfluff.core.parser.segments.base.BaseSegment, ...], List[sqlfluff.core.errors.SQLLexError]]

Take a string or TemplatedFile and return segments.

If we fail to match the whole string, then we must have found something that we cannot lex. If that happens we should package it up as unlexable and keep track of the exceptions.

static lex_match(forward_string: str, lexer_matchers: List[sqlfluff.core.parser.lexer.StringLexer])sqlfluff.core.parser.lexer.LexMatch

Iteratively match strings using the selection of submatchers.

static map_template_slices(elements: List[sqlfluff.core.parser.lexer.LexedElement], template: sqlfluff.core.templaters.base.TemplatedFile)List[sqlfluff.core.parser.lexer.TemplateElement]

Create a tuple of TemplateElement from a tuple of LexedElement.

This adds slices in the templated file to the original lexed elements. We’ll need this to work out the position in the source file.

static violations_from_segments(segments: Tuple[sqlfluff.core.parser.segments.raw.RawSegment, ...])List[sqlfluff.core.errors.SQLLexError]

Generate any lexing errors for any unlexables.

class Linter(config: Optional[sqlfluff.core.config.FluffConfig] = None, formatter: Optional[Any] = None, dialect: Optional[str] = None, rules: Optional[Union[str, List[str]]] = None, user_rules: Optional[Union[str, List[str]]] = None)

The interface class to interact with the linter.

classmethod extract_ignore_from_comment(comment: sqlfluff.core.parser.segments.raw.RawSegment)

Extract ignore mask entries from a comment segment.

classmethod extract_ignore_mask(tree: Optional[sqlfluff.core.parser.segments.base.BaseSegment])

Look for inline ignore comments and return NoQaDirectives.

fix(tree: sqlfluff.core.parser.segments.base.BaseSegment, config: Optional[sqlfluff.core.config.FluffConfig] = None, fname: Optional[str] = None, templated_file: Optional[sqlfluff.core.templaters.base.TemplatedFile] = None)Tuple[sqlfluff.core.parser.segments.base.BaseSegment, List[sqlfluff.core.errors.SQLLintError]]

Return the fixed tree and violations from lintfix when we’re fixing.

get_ruleset(config: Optional[sqlfluff.core.config.FluffConfig] = None)List[sqlfluff.core.rules.base.BaseRule]

Get hold of a set of rules.

lint(tree: sqlfluff.core.parser.segments.base.BaseSegment, config: Optional[sqlfluff.core.config.FluffConfig] = None, fname: Optional[str] = None, templated_file: Optional[sqlfluff.core.templaters.base.TemplatedFile] = None)List[sqlfluff.core.errors.SQLLintError]

Return just the violations from lintfix when we’re only linting.

classmethod lint_fix_parsed(tree: sqlfluff.core.parser.segments.base.BaseSegment, config: sqlfluff.core.config.FluffConfig, rule_set: List[sqlfluff.core.rules.base.BaseRule], fix: bool = False, fname: Optional[str] = None, templated_file: Optional[sqlfluff.core.templaters.base.TemplatedFile] = None, formatter: Optional[Any] = None)Tuple[sqlfluff.core.parser.segments.base.BaseSegment, List[sqlfluff.core.errors.SQLLintError]]

Lint and optionally fix a tree object.

classmethod lint_parsed(parsed: sqlfluff.core.linter.common.ParsedString, rule_set: List[sqlfluff.core.rules.base.BaseRule], fix: bool = False, formatter: Optional[Any] = None)

Lint a ParsedString and return a LintedFile.

lint_path(path: str, fix: bool = False, ignore_non_existent_files: bool = False, ignore_files: bool = True, processes: int = 1)sqlfluff.core.linter.linted_dir.LintedDir

Lint a path.

lint_paths(paths: Tuple[str, ...], fix: bool = False, ignore_non_existent_files: bool = False, ignore_files: bool = True, processes: int = 1)sqlfluff.core.linter.linting_result.LintingResult

Lint an iterable of paths.

classmethod lint_rendered(rendered: sqlfluff.core.linter.common.RenderedFile, rule_set: List[sqlfluff.core.rules.base.BaseRule], fix: bool = False, formatter: Optional[Any] = None)sqlfluff.core.linter.linted_file.LintedFile

Take a RenderedFile and return a LintedFile.

lint_string(in_str: str = '', fname: str = '<string input>', fix: bool = False, config: Optional[sqlfluff.core.config.FluffConfig] = None)sqlfluff.core.linter.linted_file.LintedFile

Lint a string.

Returns

an object representing that linted file.

Return type

LintedFile

lint_string_wrapped(string: str, fname: str = '<string input>', fix: bool = False)sqlfluff.core.linter.linting_result.LintingResult

Lint strings directly.

static parse_noqa(comment: str, line_no: int)

Extract ignore mask entries from a comment string.

parse_path(path: str, recurse: bool = True)Generator[sqlfluff.core.linter.common.ParsedString, None, None]

Parse a path of sql files.

NB: This a generator which will yield the result of each file within the path iteratively.

classmethod parse_rendered(rendered: sqlfluff.core.linter.common.RenderedFile, recurse: bool = True)

Parse a rendered file.

parse_string(in_str: str, fname: str = '<string>', recurse: bool = True, config: Optional[sqlfluff.core.config.FluffConfig] = None)sqlfluff.core.linter.common.ParsedString

Parse a string.

paths_from_path(path: str, ignore_file_name: str = '.sqlfluffignore', ignore_non_existent_files: bool = False, ignore_files: bool = True, working_path: str = '/home/docs/checkouts/readthedocs.org/user_builds/sqlfluff/checkouts/stable/docs/source')List[str]

Return a set of sql file paths from a potentially more ambiguous path string.

Here we also deal with the .sqlfluffignore file if present.

When a path to a file to be linted is explicitly passed we look for ignore files in all directories that are parents of the file, up to the current directory.

If the current directory is not a parent of the file we only look for an ignore file in the direct parent of the file.

static remove_templated_errors(linting_errors: List[sqlfluff.core.errors.SQLLintError])List[sqlfluff.core.errors.SQLLintError]

Filter a list of lint errors, removing those which only occur in templated slices.

render_file(fname: str, root_config: sqlfluff.core.config.FluffConfig)sqlfluff.core.linter.common.RenderedFile

Load and render a file with relevant config.

render_string(in_str: str, fname: str, config: sqlfluff.core.config.FluffConfig)sqlfluff.core.linter.common.RenderedFile

Template the file.

rule_tuples()List[sqlfluff.core.linter.common.RuleTuple]

A simple pass through to access the rule tuples of the rule set.

class Parser(config: Optional[sqlfluff.core.config.FluffConfig] = None, dialect: Optional[str] = None)

Instantiates parsed queries from a sequence of lexed raw segments.

parse(segments: Sequence[BaseSegment], recurse=True)Optional[BaseSegment]

Parse a series of lexed tokens using the current dialect.