---
title: "WASM Procedures: API Reference (Planned Design)"
---

# WASM Procedures: API Reference (Planned Design)

:::caution[Planned design: not yet available in the server]
The current `heliosdb-full` server does not run WASM procedures. SQL that
would create or call one fails with SQLSTATE `0A000`. This page describes the
planned design for this upcoming feature. Only the [Go SDK](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_language_sdks/#go-sdk) is
published. Rust, JavaScript and Python examples are illustrations: no SDK
package exists for those languages. See the
[Quick Start](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_quick_start/) for what works today.

The SQL on this page, including `CREATE SECURITY PROFILE`, the
`SECURITY PROFILE` clause, syscall filters and `ALTER PROCEDURE` options,
is the planned syntax; the current server does not accept it.
:::

**Documentation Home > User Guides > Features > API Reference**

---

## Overview

Planned API reference for the upcoming HeliosDB WASM Procedures feature, including SQL statements, host functions, and error codes. The SQL statements below are the planned syntax and are not accepted by the current server.

**Related Sections:**
- [Host Functions](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_host_functions/) - Detailed host function documentation
- [Procedure Management](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_procedure_management/) - Managing procedures
- [Language SDKs](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_language_sdks/) - SDK-specific APIs

---

## API Reference

### SQL Statements

#### CREATE PROCEDURE

```sql
-- Planned syntax for the upcoming WASM procedures feature; the current server does not accept it.
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

```sql
-- Planned syntax for the upcoming WASM procedures feature; the current server does not accept it.
ALTER PROCEDURE name
  SET SOURCE '/path/to/new.wasm'
  | SET SECURITY PROFILE 'profile'
  | SET log_level = 'level'
  | SET option = value;
```

#### DROP PROCEDURE

```sql
DROP PROCEDURE [IF EXISTS] name [CASCADE];
```

#### CALL

```sql
CALL procedure_name(args);
SELECT procedure_name(args);
```

### Host Function Reference

The WASM host links its functions in the `env` import module:
`heliosdb_execute`, `heliosdb_begin_tx`, `heliosdb_commit_tx`,
`heliosdb_rollback_tx`, `heliosdb_storage_write`, `heliosdb_log`,
`heliosdb_query`, `heliosdb_storage_read`, `heliosdb_fetch_rows` and
`heliosdb_emit_event`. There are no HTTP, metrics or capability-request host
functions. Signatures, return codes and the matching Go SDK calls are in
[Host Functions](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_host_functions/).

### 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:

```sql
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:

```sql
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:

```sql
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:

```sql
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:

```sql
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:

```sql
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

```sql
-- 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

```sql
-- Planned syntax for the upcoming WASM procedures feature; the current server does not accept it.
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:**
```sql
-- Planned syntax for the upcoming WASM procedures feature; the current server does not accept it.
CREATE PROCEDURE name(params) RETURNS type LANGUAGE wasm AS source;
```

**Call Procedure:**
```sql
SELECT procedure_name(args);
```

**View Metrics:**
```sql
SELECT * FROM heliosdb_procedure_metrics WHERE procedure_name = 'name';
```

**View Errors:**
```sql
SELECT * FROM heliosdb_procedure_errors WHERE procedure_name = 'name';
```

## Next Steps

- **[Host Functions](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_host_functions/)** - Detailed host function documentation
- **[Language SDKs](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_language_sdks/)** - SDK-specific APIs
- **[Conclusion](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_conclusion/)** - Summary and resources

---

**Navigation:** [← Migration Guide](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_migration_guide/) | [Index](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_user_guide/) | [Conclusion →](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_conclusion/)