Query API Reference
gluon.query()
Execute a SQL query and return rows as objects.
javascript
const rows = await gluon.query(sql, options);
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
sql | string | ✅ | SQL query to execute |
options.datasource | string | ✅ | Target datasource name |
options.limit | number | ❌ | Max rows to return (default: 1000) |
options.timeoutMs | number | ❌ | Query timeout in ms (default: 10000) |
Returns
Returns a Promise that resolves to an array of row objects where keys are column names.
Example
javascript
const users = await gluon.query(
'SELECT id, name, email FROM users WHERE active = true',
{ datasource: 'production' }
);
// Result: [{ id: 1, name: 'Alice', email: 'alice@example.com' }, ...]
users.forEach(user => {
console.log(user.name, user.email);
});
gluon.queryWithMeta()
Execute a SQL query and return rows with metadata (column types, execution time).
javascript
const result = await gluon.queryWithMeta(sql, options);
Parameters
Same as gluon.query().
Returns
typescript
Promise<{
rows: Object[]; // Array of row objects
columns: Array<{ // Column metadata
name: string;
type: string;
}>;
rowCount: number; // Number of rows returned
executionTimeMs: number; // Query execution time in ms
}>
Example
javascript
const result = await gluon.queryWithMeta(
'SELECT * FROM orders WHERE created_at > NOW() - INTERVAL \'7 days\'',
{ datasource: 'analytics' }
);
console.log(`Found ${result.rowCount} orders`);
console.log(`Query took ${result.executionTimeMs}ms`);
// Inspect column types
result.columns.forEach(col => {
console.log(`${col.name}: ${col.type}`);
});
// Process rows
result.rows.forEach(order => {
console.log(order.order_id, order.total);
});
Error Handling
Always wrap queries in try-catch blocks:
javascript
try {
const data = await gluon.query('SELECT * FROM users', {
datasource: 'my_db'
});
renderTable(data);
} catch (error) {
console.error('Query failed:', error.message);
showErrorMessage(error.message);
}
Common Errors
| Error | Cause | Solution |
|---|---|---|
datasource is required | Missing datasource option | Add datasource to options |
Datasource "x" not found | Invalid datasource name | Check datasource name in project |
Query timeout | Query took too long | Optimize query or increase timeoutMs |
Permission denied | Insufficient database permissions | Check database user permissions |
Best Practices
1. Always Specify Limits
Avoid fetching more data than you need:
javascript
// Good - explicit limit
const rows = await gluon.query(
'SELECT * FROM logs ORDER BY created_at DESC LIMIT 100',
{ datasource: 'logs_db' }
);
// Also good - use the limit option
const rows = await gluon.query(
'SELECT * FROM logs ORDER BY created_at DESC',
{ datasource: 'logs_db', limit: 100 }
);
2. Use Parameterized Values Carefully
The SDK executes raw SQL. For user inputs, sanitize values:
javascript
// If using dynamic values, escape them properly
const safeName = name.replace(/'/g, "''");
const query = `SELECT * FROM users WHERE name = '${safeName}'`;
3. Handle Loading States
javascript
document.getElementById('loading').style.display = 'block';
try {
const data = await gluon.query(sql, { datasource: 'db' });
renderData(data);
} finally {
document.getElementById('loading').style.display = 'none';
}
4. Normalize Datasource Names
Datasource names are case-insensitive. These are equivalent:
javascript
{ datasource: 'MyDatabase' }
{ datasource: 'mydatabase' }
{ datasource: 'MYDATABASE' }