Overview
Thequery command allows you to execute arbitrary SQL queries against your local blockchain database. Results are automatically formatted as readable tables, making it easy to analyze election data, aggregate votes, and explore the blockchain state.
Syntax
Parameters
The SQL query to execute against the blockchain database. Must be a valid SQLite query.Note: Enclose the entire query in quotes to prevent shell interpretation of special characters.
Database Schema
The blockchain database contains several key tables:Core Tables
- blocks: Contains all blockchain blocks
- results: Stores election results from each block
- stations: Polling station information
- candidates: Candidate details
- parties: Political party information
- wards: Ward-level regional data
- constituencies: Constituency-level regional data
- counties: County-level regional data
Schema Details
Examples
Simple Query
Query all results:Aggregate by Candidate
Get total votes per candidate in a constituency:Count Blocks
Check total number of blocks:Latest Results
Get most recent submissions:Vote Summary by County
Candidate Performance by Ward
Query Requirements
Required columns for result queries:candidate- Candidate namevotes- Vote countward- Ward nameconstituency- Constituency namecounty- County nameparty- Party name or abbreviation
Table Formatting
Query results are automatically formatted using thetabled library:
- Headers: Column names are displayed in the first row
- Alignment: Numbers are right-aligned, text is left-aligned
- Borders: ASCII borders separate columns and rows
- Spacing: Automatic column width adjustment
Supported SQL Features
As Ubu-Block uses SQLite, you have access to:Standard Operations
SELECT,FROM,WHERE,GROUP BY,ORDER BYINNER JOIN,LEFT JOIN,RIGHT JOIN- Aggregate functions:
COUNT(),SUM(),AVG(),MIN(),MAX() - String functions:
LIKE,UPPER(),LOWER(),SUBSTR() - Math operations:
+,-,*,/,%
SQLite-Specific
LIMITandOFFSETfor paginationDISTINCTfor unique valuesCASEstatements for conditional logic- Common Table Expressions (CTEs) with
WITH - Window functions (SQLite 3.25+)
Read-Only: The query command only reads data. It cannot modify the blockchain using
UPDATE, DELETE, or INSERT statements. The blockchain is immutable and changes only through the submit command.Use Cases
Election Results Analysis
Election Results Analysis
Aggregate and analyze election results across different geographic levels (station, ward, constituency, county).
Turnout Calculation
Turnout Calculation
Compare submitted votes against registered voter counts to calculate turnout percentages.
Data Quality Checks
Data Quality Checks
Identify anomalies, outliers, or suspicious patterns in submitted results.
Reporting
Reporting
Generate reports for media, observers, and stakeholders with formatted data.
Blockchain Inspection
Blockchain Inspection
Examine blockchain structure, block contents, and submission history.
Advanced Queries
Results Timeline
Track when results were submitted:Duplicate Detection
Find stations that submitted multiple times:Block Statistics
Error Handling
SQL Syntax Error
- Typos in keywords (e.g.,
FORMinstead ofFROM) - Missing quotes around strings
- Unmatched parentheses
- Invalid column names
Table Not Found
Column Not Found
PRAGMA table_info(table_name) to list columns.
Performance Tips
- Use Indexes: Key columns are indexed, so filtering on
station_id,candidate_id, orblock_heightis fast - Limit Results: Use
LIMITfor large datasets to avoid overwhelming output - Aggregate Early: Use
WHEREclauses beforeGROUP BYto reduce data processed - Avoid SELECT*: Specify only needed columns for better performance
Troubleshooting
Empty Results
If queries return no data:- Confirm blocks have been added with
SELECT COUNT(*) FROM blocks - Check if results were submitted with
SELECT COUNT(*) FROM results - Verify joins are correct (use
LEFT JOINto debug)
Incorrect Values
If results don’t match expectations:- Validate data in individual tables first
- Check for NULL values affecting aggregations
- Verify foreign key relationships are correct
Implementation Details
The query command is implemented inapps/cli/src/query.rs:13-22 and:
- Connects to the main blockchain database (read-only)
- Uses
sqlxfor async database operations - Formats output with the
tabledcrate - Supports any valid SQLite query
- Returns structured data as
VoteResultfor special formatting
Next Steps
Validate Chain
Verify blockchain integrity
Database Schema
Explore the complete database schema
REST API
Query data via HTTP API
Submit Results
Add more data to query