{"id":43868,"library":"spreadsheet-sql","title":"spreadsheet-sql","description":"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.","status":"active","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/JumpeiArashi/spreadsheet-sql","tags":["javascript","google","spreadsheet","sql","charts","visualization","typescript"],"install":[{"cmd":"npm install spreadsheet-sql","lang":"bash","label":"npm"},{"cmd":"yarn add spreadsheet-sql","lang":"bash","label":"yarn"},{"cmd":"pnpm add spreadsheet-sql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for authentication with private spreadsheets.","package":"google-auth-library","optional":false}],"imports":[{"note":"CommonJS require also works, but ESM is preferred when using TypeScript.","wrong":"const PublicSpreadsheet = require('spreadsheet-sql').PublicSpreadsheet","symbol":"PublicSpreadsheet","correct":"import { PublicSpreadsheet } from 'spreadsheet-sql'"},{"note":"Must import PrivateSpreadsheet specifically; it's a named export.","wrong":"const spreadsheet-sql = require('spreadsheet-sql'); new spreadsheet-sql.PrivateSpreadsheet(...)","symbol":"PrivateSpreadsheet","correct":"import { PrivateSpreadsheet } from 'spreadsheet-sql'"},{"note":"Since v1.0.0, the constructor accepts an AuthClient from google-auth-library instead of OAuth2 parameters.","wrong":"new PrivateSpreadsheet(sheetKey, sheetName, clientId, clientSecret, redirectUrn, refreshToken)","symbol":"PrivateSpreadsheet (constructor)","correct":"new PrivateSpreadsheet(sheetKey, sheetName, authClient)"}],"quickstart":{"code":"import { PublicSpreadsheet } from 'spreadsheet-sql';\n\nconst spreadsheet = new PublicSpreadsheet('YOUR_SPREADSHEET_KEY', 'Sheet1');\nspreadsheet.query('SELECT * WHERE A = \"user1\"')\n  .then(result => {\n    console.log(result);\n  })\n  .catch(err => {\n    console.error(err);\n  });","lang":"typescript","description":"Query a public Google Spreadsheet using SQL-like syntax. Shows instantiation, query, and promise handling."},"warnings":[{"fix":"Create an AuthClient (e.g., OAuth2Client) with credentials and pass it as the third argument.","message":"PrivateSpreadsheet constructor signature changed in v1.0.0: from (key, sheet, clientId, secret, redirect, refresh) to (key, sheet, authClient).","severity":"breaking","affected_versions":">=0.x <1.0.0"},{"fix":"Ensure the first row contains exactly the column names you want to query.","message":"First 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).","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Refer to https://developers.google.com/chart/interactive/docs/querylanguage for supported syntax.","message":"Query language is limited to Google Visualization API Query Language, not full SQL. Joins, subqueries, etc., are not supported.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use GoogleAuth.getClient() with scopes to obtain an AuthClient automatically.","message":"The 'google-auth-library' package now prefers application default credentials; manual OAuth2Client creation is still supported but not recommended.","severity":"deprecated","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'1.1.1':13 '2021':85 'allow':25 'alway':67 'api':22 'auth':43,51 'authclient':53 'break':54 'cadenc':78 'chang':55 'chart':90 'claus':33 'column':70 'current':14 'data':36 'definit':76 'direct':60 'first':64 'googl':5,20,50,87 'google-auth-librari':49 'header':71 'javascript':86 'languag':24 'last':81 'librari':17,52 'like':10,32 'low':80 'oauth2':61 'paramet':62 'previous':58 'privat':45 'public':40 'queri':4,23 'releas':77 'requir':59 'row':65 'select':26 'ship':72 'spreadsheet':2,6,35,41,46,88 'spreadsheet-sql':1 'sql':3,9,31,89 'sql-like':8,30 'stabl':15 'support':38 'syntax':11 'treat':68 'type':75 'typescript':74,92 'updat':82 'use':7 'v1':57 'version':12 'via':47 'visual':21,91 'wrap':18","created_at":"2026-06-05T17:01:51.888798+00:00","updated_at":"2026-06-05T17:01:51.888798+00:00","problems":[{"fix":"Use `import { PrivateSpreadsheet } from 'spreadsheet-sql'`.","cause":"Importing the default export instead of the named export.","error":"TypeError: PrivateSpreadsheet is not a constructor"},{"fix":"Remove unsupported clauses; refer to Google Visualization Query Language spec.","cause":"Query contains LABEL or other unsupported clauses; the library only supports a subset of Query Language.","error":"Error: Invalid query: LABEL clause is not supported"},{"fix":"Double-check the spreadsheet key and worksheet name, and ensure the spreadsheet has at least view access.","cause":"Spreadsheet key or worksheet name is incorrect, or the spreadsheet is not publicly accessible.","error":"Cannot read property 'query' of undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/JumpeiArashi/spreadsheet-sql#readme","github":"https://github.com/JumpeiArashi/spreadsheet-sql","docs":null,"changelog":null,"pypi":null,"npm":"spreadsheet-sql","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}