spreadsheet-sql

library1.1.1jsnpmunverified

Query Google Spreadsheets using SQL-like syntax. Version 1.1.1 currently stable. The library wraps the Google Visualization API Query Language, allowing SELECT, WHERE, and other SQL-like clauses on spreadsheet data. It supports both public spreadsheets (no auth) and private spreadsheets via any google-auth-library AuthClient (breaking change from v1: previously required direct OAuth2 parameters). The first row is always treated as column headers. Ship with TypeScript type definitions. Release cadence is low, last update was in 2021.

database

npm install spreadsheet-sql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SPREADSHEET-SQL

spreadsheet-sql

databasejavascriptv1.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PublicSpreadsheet

✓ import { PublicSpreadsheet } from 'spreadsheet-sql'

✗ const PublicSpreadsheet = require('spreadsheet-sql').PublicSpreadsheet

CommonJS require also works, but ESM is preferred when using TypeScript.

PrivateSpreadsheet

✓ import { PrivateSpreadsheet } from 'spreadsheet-sql'

✗ const spreadsheet-sql = require('spreadsheet-sql'); new spreadsheet-sql.PrivateSpreadsheet(...)

Must import PrivateSpreadsheet specifically; it's a named export.

PrivateSpreadsheet (constructor)

✓ new PrivateSpreadsheet(sheetKey, sheetName, authClient)

✗ new PrivateSpreadsheet(sheetKey, sheetName, clientId, clientSecret, redirectUrn, refreshToken)

Since v1.0.0, the constructor accepts an AuthClient from google-auth-library instead of OAuth2 parameters.

Query a public Google Spreadsheet using SQL-like syntax. Shows instantiation, query, and promise handling.

import { PublicSpreadsheet } from 'spreadsheet-sql'; const spreadsheet = new PublicSpreadsheet('YOUR_SPREADSHEET_KEY', 'Sheet1'); spreadsheet.query('SELECT * WHERE A = "user1"') .then(result => { console.log(result); }) .catch(err => { console.error(err); });

Debug

Known issues

breakingPrivateSpreadsheet constructor signature changed in v1.0.0: from (key, sheet, clientId, secret, redirect, refresh) to (key, sheet, authClient).

fix

Create an AuthClient (e.g., OAuth2Client) with credentials and pass it as the third argument.

affects: >=0.x <1.0.0

gotchaFirst row of spreadsheet is always treated as column headers. Queries referencing columns must use header names (e.g., column letters A, B, or header names after defining).

fix

Ensure the first row contains exactly the column names you want to query.

affects: >=0.0.0

gotchaQuery language is limited to Google Visualization API Query Language, not full SQL. Joins, subqueries, etc., are not supported.

fix

Refer to https://developers.google.com/chart/interactive/docs/querylanguage for supported syntax.

affects: >=0.0.0

deprecatedThe 'google-auth-library' package now prefers application default credentials; manual OAuth2Client creation is still supported but not recommended.

fix

Use GoogleAuth.getClient() with scopes to obtain an AuthClient automatically.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: PrivateSpreadsheet is not a constructor

Importing the default export instead of the named export.

fix

Use `import { PrivateSpreadsheet } from 'spreadsheet-sql'`.

Error: Invalid query: LABEL clause is not supported

Query contains LABEL or other unsupported clauses; the library only supports a subset of Query Language.

fix

Remove unsupported clauses; refer to Google Visualization Query Language spec.

Cannot read property 'query' of undefined

Spreadsheet key or worksheet name is incorrect, or the spreadsheet is not publicly accessible.

fix

Double-check the spreadsheet key and worksheet name, and ensure the spreadsheet has at least view access.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

google-auth-libraryrequiredRequired for authentication with private spreadsheets.

Agent activity

7 hits · last 30 days

node