HQL Linter & Formatter

A VS Code extension that provides real-time linting and formatting for HQL (Hive Query Language) files. Catch syntax errors instantly before running resource-intensive queries.

Why This Extension?

Running HQL queries in production environments can be extremely resource-intensive and time-consuming—sometimes taking hours to complete. When a query fails due to syntax errors after consuming significant computational resources, it wastes both time and infrastructure capacity.

This extension solves that problem by providing instant feedback as you write HQL code, catching common syntax errors and style issues before you execute your queries. Save hours of debugging time and computational resources by validating your HQL syntax right in your editor.

Features

🔍 Real-Time Linting

Detects syntax errors and issues as you type:

• Syntax errors: Unclosed string literals, unbalanced parentheses
• Missing clauses: JOIN without ON/USING, incomplete statements
• Style issues: Lowercase keywords, trailing whitespace
• Best practices: SELECT * usage, GROUP BY without aggregates
• Quick fixes: One-click fixes for common issues (uppercase keywords, add semicolons, remove whitespace, close quotes)

✨ Professional-Grade Formatting

Powered by the industry-standard sql-formatter library with extensive customization:

• Case control: Separate settings for keywords, data types, functions, and identifiers (upper/lower/preserve)
• Indentation styles: Standard, tabular left-aligned, or tabular right-aligned
• Flexible spacing: Control tabs vs spaces, operator density, query separation
• Configurable layout: Semicolon placement, line breaks, and more
• 10+ formatting options to match your team's style guide

💡 Intelligent IntelliSense

• 150+ keywords and functions with context-aware auto-completion
• Enhanced hover documentation with syntax, examples, and links to Apache Hive docs
• Signature help showing parameter hints and documentation as you type
• 9 code snippets for common patterns (CREATE TABLE, JOINs, window functions, CTEs, etc.)
• Quick fixes for common issues with one-click solutions

🎨 Syntax Highlighting

Full syntax highlighting support for:

• HQL keywords and clauses
• Functions and data types
• String literals and comments
• Table and column identifiers

Installation

From Visual Studio Marketplace

1. Open VS Code
2. Go to the Extensions view (Ctrl+Shift+X or Cmd+Shift+X on Mac)
3. Search for "HQL Linter & Formatter"
4. Click Install

Or install directly from the Visual Studio Marketplace.

From Source

1. Clone this repository
2. Install dependencies:

   npm install
   

3. Build the extension:

   npm run compile
   

4. Press F5 in VS Code to launch the extension in debug mode

For Development

Run the extension in watch mode for automatic recompilation:

npm run watch

Usage

Opening HQL Files

The extension automatically activates when you open files with .hql or .hive extensions.

Formatting

• Format entire document: Ctrl+Shift+I (Windows/Linux) or Cmd+Shift+I (Mac)
• Format selection: Select text, then right-click → "Format Selection"
• Command Palette: HQL: Format Document

Linting

Linting runs automatically when you:

• Open an HQL file
• Edit HQL code
• Save the file

View diagnostics in:

• Inline error squiggles
• Problems panel (Ctrl+Shift+M)
• Hover tooltips

Quick Fixes

When the linter detects fixable issues:

1. Click the lightbulb icon 💡 or press Ctrl+.
2. Select the suggested fix
3. The code is automatically corrected

Configuration

Customize the extension behavior in VS Code settings:

{
  // Linting
  "hql.linting.enabled": true,
  "hql.linting.severity": "Warning", // Error, Warning, Information, or Hint
  "hql.linting.maxFileSize": 1048576, // Maximum file size to lint (1MB)
  "hql.linting.rules.keywordCasing": true,
  "hql.linting.rules.semicolon": true,
  "hql.linting.rules.stringLiteral": true,
  "hql.linting.rules.parentheses": true,
  "hql.linting.rules.trailingWhitespace": true,

  // Formatting
  "hql.formatting.enabled": true,
  "hql.formatting.tabWidth": 2,
  "hql.formatting.useTabs": false,
  "hql.formatting.keywordCase": "upper", // upper, lower, or preserve
  "hql.formatting.dataTypeCase": "upper",
  "hql.formatting.functionCase": "upper",
  "hql.formatting.identifierCase": "preserve",
  "hql.formatting.indentStyle": "standard", // standard, tabularLeft, or tabularRight
  "hql.formatting.linesBetweenQueries": 1,
  "hql.formatting.denseOperators": false,
  "hql.formatting.newlineBeforeSemicolon": false,

  // Logging
  "hql.logLevel": "info" // debug, info, warn, or error
}

Configuration Options

Linting

Formatting

Logging

Example

Before:

select id, name, sum(amount) from users left join orders on users.id = orders.user_id where status = 'active' group by id, name

After:

Examples

Before Formatting

select id, name, sum(amount) from users left join orders on users.id = orders.user_id where status = 'active' group by id, name

After Formatting

SELECT id, name, SUM(amount)
FROM users
LEFT JOIN orders
  ON users.id = orders.user_id
WHERE status = 'active'
GROUP BY id, name;

Linting in Action

-- ❌ Error: Unclosed string literal
SELECT name FROM users WHERE status = 'active

-- ❌ Error: Unbalanced parentheses
SELECT COUNT(id FROM users

-- ⚠️ Warning: JOIN without ON clause
SELECT * FROM users JOIN orders

-- ℹ️ Info: Consider specifying columns
SELECT * FROM users

-- ℹ️ Info: Missing semicolon
SELECT id FROM users

Supported HQL Features

• Keywords: SELECT, FROM, WHERE, JOIN, GROUP BY, ORDER BY, etc.
• Functions: COUNT, SUM, AVG, MIN, MAX, CONCAT, COLLECT_LIST, etc.
• Data Types: INT, BIGINT, STRING, DOUBLE, ARRAY, MAP, STRUCT, etc.
• Joins: INNER, LEFT, RIGHT, FULL OUTER, CROSS
• Partitioning: PARTITION BY, DISTRIBUTE BY, CLUSTER BY
• DDL: CREATE, DROP, ALTER, TRUNCATE, SHOW, DESCRIBE

Development

Building

npm run compile

Watch Mode

npm run watch

Testing

npm test

Project Structure

├── src/
│   ├── extension.ts      # Extension entry point
│   ├── linter.ts         # Linting rules and logic
│   ├── formatter.ts      # Formatting logic
│   └── diagnostics.ts    # Diagnostics provider
├── syntaxes/
│   └── hql.tmLanguage.json   # Syntax highlighting grammar
├── examples/             # Example HQL files for testing
├── package.json          # Extension manifest
└── tsconfig.json         # TypeScript configuration

Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

License

MIT

Acknowledgments

Built with ❤️ to make HQL development faster and more efficient.

## License

MIT