WASM Procedures: API Reference

WASM Procedures: API Reference

Documentation Home > User Guides > Features > API Reference

---

Overview

Complete API reference for HeliosDB WASM Procedures, including SQL statements, host functions, and error codes.

Related Sections:

• Host Functions - Detailed host function documentation
• Procedure Management - Managing procedures
• Language SDKs - SDK-specific APIs

---

API Reference

SQL Statements

CREATE PROCEDURE

CREATE [OR REPLACE] PROCEDURE name (params)
[RETURNS type]
LANGUAGE wasm
[SECURITY PROFILE 'profile']
[WITH (options)]
AS source;

Options:

• precompile: boolean - Precompile module
• compilation_tier: ‘interpreter’ | ‘baseline’ | ‘optimizing’
• fuel_metering: boolean - Enable fuel metering
• fuel_limit: integer - Fuel limit
• profiling: boolean - Enable profiling
• debug_mode: boolean - Enable debug mode

ALTER PROCEDURE

ALTER PROCEDURE name
  SET SOURCE '/path/to/new.wasm'
  | SET SECURITY PROFILE 'profile'
  | SET log_level = 'level'
  | SET option = value;

DROP PROCEDURE

DROP PROCEDURE [IF EXISTS] name [CASCADE];

CALL

CALL procedure_name(args);
SELECT procedure_name(args);

Host Function Reference

Database:

• exec_sql(sql: string) -> ResultSet
• exec_prepared(stmt_id: i64) -> ResultSet
• prepare_statement(sql: string) -> i64
• begin_transaction() -> Transaction
• commit_transaction(tx: Transaction) -> Result<()>
• rollback_transaction(tx: Transaction) -> Result<()>

Key-Value:

• kv_get(key: bytes) -> Option<bytes>
• kv_set(key: bytes, value: bytes) -> Result<()>
• kv_delete(key: bytes) -> Result<()>

Document:

• doc_get(collection: string, id: string) -> Option<JSON>
• doc_insert(collection: string, doc: JSON) -> string
• doc_update(collection: string, id: string, doc: JSON) -> Result<()>
• doc_delete(collection: string, id: string) -> Result<()>

Graph:

• graph_query(query: string) -> GraphResult
• graph_shortest_path(from: NodeId, to: NodeId) -> Path

Vector:

• vector_search(collection: string, vector: Vec<f32>, top_k: i32) -> Vec<Match>
• vector_insert(collection: string, vector: Vec<f32>, metadata: JSON) -> string

HTTP:

• http_get(url: string) -> HTTPResponse
• http_post(url: string, body: bytes, headers: Map) -> HTTPResponse
• http_put(url: string, body: bytes, headers: Map) -> HTTPResponse
• http_delete(url: string) -> HTTPResponse

Logging:

• log_trace(message: string)
• log_debug(message: string)
• log_info(message: string)
• log_warn(message: string)
• log_error(message: string)

Metrics:

• metric_increment(name: string, value: i64)
• metric_gauge(name: string, value: f64)
• metric_histogram(name: string, value: f64)

Crypto:

• sha256(data: bytes) -> bytes
• sha512(data: bytes) -> bytes
• blake3(data: bytes) -> bytes
• random_bytes(count: i32) -> bytes

Time:

• current_timestamp() -> i64
• format_timestamp(timestamp: i64, format: string) -> string

Security:

• request_capability(cap: Capability) -> Result<()>
• check_capability(cap: Capability) -> bool

Error Codes

Code	Name	Description
01000	WASM_COMPILATION_ERROR	Failed to compile WASM module
01001	WASM_INSTANTIATION_ERROR	Failed to instantiate module
01002	WASM_EXECUTION_ERROR	Procedure execution failed
01003	WASM_TIMEOUT	Execution exceeded time limit
01004	WASM_MEMORY_EXCEEDED	Memory limit exceeded
01005	WASM_FUEL_EXHAUSTED	Fuel limit exhausted
01006	WASM_SECURITY_VIOLATION	Security capability violation
01007	WASM_PERMISSION_DENIED	Permission denied
01008	WASM_INVALID_PARAMETER	Invalid parameter
01009	WASM_MODULE_NOT_FOUND	Procedure not found

---

System Catalogs

heliosdb_procedures

Information about all procedures:

SELECT * FROM heliosdb_procedures;

Columns:

• name: Procedure name
• language: ‘wasm’
• security_profile: Security profile name
• size_bytes: WASM module size
• created_at: Creation timestamp
• last_modified: Last modification timestamp
• version: Current version

heliosdb_procedure_metrics

Performance metrics:

SELECT * FROM heliosdb_procedure_metrics;

Columns:

• procedure_name: Procedure name
• total_calls: Total number of calls
• successful_calls: Successful executions
• failed_calls: Failed executions
• success_rate: Success rate percentage
• avg_execution_time_ms: Average execution time
• min_execution_time_ms: Minimum execution time
• max_execution_time_ms: Maximum execution time
• p50_execution_time_ms: 50th percentile
• p95_execution_time_ms: 95th percentile
• p99_execution_time_ms: 99th percentile

heliosdb_procedure_errors

Error tracking:

SELECT * FROM heliosdb_procedure_errors;

Columns:

• procedure_name: Procedure name
• error_message: Error message
• error_count: Number of occurrences
• last_occurrence: Last occurrence timestamp
• stack_trace: Stack trace (if available)
• source_location: Source code location

heliosdb_procedure_logs

Procedure logs:

SELECT * FROM heliosdb_procedure_logs;

Columns:

• timestamp: Log timestamp
• procedure_name: Procedure name
• log_level: Log level (trace, debug, info, warn, error)
• message: Log message
• execution_id: Execution identifier

heliosdb_wasm_cache_stats

Module cache statistics:

SELECT * FROM heliosdb_wasm_cache_stats;

Columns:

• cached_modules: Number of cached modules
• cache_hits: Cache hits
• cache_misses: Cache misses
• hit_rate: Hit rate percentage
• evictions: Number of evictions

heliosdb_wasm_pool_stats

Instance pool statistics:

SELECT * FROM heliosdb_wasm_pool_stats;

Columns:

• procedure_name: Procedure name
• pool_size: Configured pool size
• available_instances: Available instances
• in_use_instances: Instances in use
• total_acquisitions: Total acquisitions
• avg_acquisition_time_ms: Average acquisition time

---

Configuration Parameters

Global Settings

-- Cache configuration
SET heliosdb.wasm_module_cache_size = 1000;
SET heliosdb.wasm_module_cache_ttl = 3600;
SET heliosdb.wasm_module_cache_enabled = true;

-- Pool configuration
SET heliosdb.wasm_instance_pool_size = 10;
SET heliosdb.wasm_instance_max_age_seconds = 300;
SET heliosdb.wasm_instance_max_executions = 1000;

-- Memory configuration
SET heliosdb.wasm_memory_pool_size_mb = 1024;
SET heliosdb.wasm_memory_pooling_enabled = true;

-- Logging configuration
SET heliosdb.procedure_log_level = 'info';
SET heliosdb.procedure_log_retention_days = 30;

-- Execution limits
SET heliosdb.wasm_default_fuel_limit = 1000000000;
SET heliosdb.wasm_default_memory_limit_mb = 512;
SET heliosdb.wasm_default_timeout_ms = 30000;

Procedure-Specific Settings

ALTER PROCEDURE my_procedure
  SET fuel_limit = 10000000000
  SET fuel_metering = false
  SET compilation_tier = 'optimizing'
  SET profiling = true
  SET debug_mode = false
  SET log_level = 'info';

---

Key Takeaways

1. Complete SQL API: Full DDL support for procedure management
2. Rich Host Functions: 40+ host functions across 8 categories
3. System Catalogs: Comprehensive metadata and metrics
4. Error Codes: Standardized error codes for diagnostics
5. Configuration: Flexible global and per-procedure settings

Quick Reference

Create Procedure:

CREATE PROCEDURE name(params) RETURNS type LANGUAGE wasm AS source;

Call Procedure:

SELECT procedure_name(args);

View Metrics:

SELECT * FROM heliosdb_procedure_metrics WHERE procedure_name = 'name';

View Errors:

SELECT * FROM heliosdb_procedure_errors WHERE procedure_name = 'name';

Next Steps

• Host Functions - Detailed host function documentation
• Language SDKs - SDK-specific APIs
• Conclusion - Summary and resources

---

Navigation: ← Migration Guide | Index | Conclusion →