Skip to main content

J1QL Style Guide

As with all query languages there are preferred conventions to have consistency between queries and ultimately make them more readable. This page documentes the preferred style for writing and sharing J1QL.

Introduction​

This style guide provides best practices and conventions for writing J1QL (JupiterOne Query Language) queries. Adhering to these guidelines will ensure your queries are readable, maintainable, and efficient.

Formatting​

Indentation​

  • Use two spaces for indentation to improve readability
  • Wrapped lines should have additional indentation

Line Length​

  • Keep lines under 120 characters where possible for better readability in various editors

Whitespace​

  • Use whitespace around operators (e.g., =, !=, >, <) for clarity
  • Include a space after commas in lists

Case Sensitivity​

  • Use uppercase for J1QL keywords and functions to maintain consistency
  • Entity properties should be in the case as defined in the data model

Naming Conventions​

Aliases​

  • Use meaningful aliases for entities and properties to improve query understandability
  • Aliases should be camelCase for consistency

Query Structure​

FIND Clause​

  • Begin queries with the FIND keyword followed by the entity type
  • Use the AS keyword for aliasing entities and properties when needed

WITH and WHERE Clause​

  • Use the WITH and WHERE clauses to filter results based on specific criteria
  • Group related conditions using parentheses for clarity

RETURN Statement​

  • Clearly specify what data to return using the RETURN statement for complex queries
  • RETURN should always be on a new line

Operators​

Logical Operators​

  • Use AND, OR and ! to combine or exclude conditions
  • Group conditions with parentheses to override precedence

Comparison Operators​

  • Use =, !=, <, >, <=, >=, ^= and $= for comparisons and filters
  • Use / ... / for regex-based matching when applicable
  • The operand, when representing a string, should be enclosed in double quotes "

Functions​

Usage​

  • Use built-in functions (e.g., COUNT, SUM, AVG) to perform calculations or transform data
  • Always include parentheses, even if there are no arguments

Comments​

Block and Inline Comments​

  • Use /* and */ for block comments to describe overall query purpose or methodology at the beginning of the query
  • Use /* and */ for inline comments at the end of the line to which they apply

Examples​

Find all User entities

FIND User AS u
RETURN u.displayName, u.email

Find open vulnerabilities with critical severity

FIND Vulnerability WITH severity = "critical" AS v
RETURN v.displayName, v.score

Contents