Code Engine - Powered by Wasm

Prerequisites

You can build Wasm extensions for SingleStore on Mac, Windows, or Linux. To build Wasm extensions, you'll need:

• (For Mac) Homebrew package manager.

• Git

• Docker

• Visual Studio Code

Select the Wasm ABI

When a Wasm function is created, you can specify one of the following Application Binary Interfaces (ABIs): Basic or Canonical. The default ABI type is Canonical, unless specified explicitly.

• Basic: This is the bare-bones Wasm ABI. It supports only 32-bit and 64-bit integers and floating point numbers.

• Canonical: This ABI type is defined by the Canonical ABI specification (a part of the Interface Types proposal). It is a superset of Basic ABI, and it allows usage of structured and complex interface types.

user-function-name: func() -> string; 

SELECT user_function_name();

Configure Wasm

Use the following global variables to configure the Code Engine for Wasm extensibility:

Wasm Data Type Coercions

The following table describes how database types are coerced to and from Wasm ABI types when using explicitly-typed UDFs/TVFs. Empty cells indicate that automatic coercion is not available currently, and you must cast that SingleStore database type to another data type for which data type conversion is available:

Improve Wasm Function Performance

Here are some examples of ways to increase the speed of your Wasm code:

• Compile the Wasm function in "release" mode and not in debug mode. To compile in release mode,

  • In Rust, pass the --release flag to cargo, and

  • In C/C++, pass the -O3 option to the compiler.

• If your program can benefit by building data structures in advance, you may improve performance by maintaining a cache in your Wasm program. For example, you can cache reusable data between function calls.

  The following example caches compiled regular expressions so it does not have to compile the regular expression argument again for every row passed to the function:

  Rust

  Copy

  wit_bindgen_rust::export!("s2regex.wit");
  use regex::Regex;
  use std::cell::RefCell;
  use std::collections::HashMap;
  
  struct S2regex;
  
  thread_local! {
      static COMPILED_RGXS: RefCell<HashMap<String, Regex>> = RefCell::new(HashMap::new());
  }
  
  impl s2regex::S2regex for S2regex {
      fn capture(input: String, pattern: String) -> String {
          COMPILED_RGXS.with(|c| {
              let mut map = c.borrow_mut();
              let re = map
                  .entry(pattern)
                  .or_insert_with_key(|pattern| Regex::new(pattern).unwrap());
              re.captures(&input)
                  .and_then(|c| c.get(1))
                  .map(|c| c.as_str())
                  .unwrap_or_default()
                  .to_string()
          })
      }
  }

  The following query has to compile the regular expression only for the first row:

  SQL

  Copy

  SELECT * FROM tbl WHERE s2regex(tbl.col, '<reg_exp_string>') = "val";

Troubleshooting

How to find bug(s) in the Wasm code when it is called from SQL?

Debug the code outside of the database. You may use a test harness, or single-step through the code in a debugger.

FAQs

• Can I use a Wasm binary outside of the SingleStore database once it is imported into the database?

  No. Once a Wasm binary is imported into a SingleStore database, you cannot use it for applications outside the database. However, you can make a copy of the binary and use it instead.

• What happens if there is a mismatch between the WIT file and the generated code?

  A mismatch may cause a Wasm trap or unexpected results. The exact behavior depends on how the Wasm program interprets the arguments.

• Can I reverse engineer a Wasm binary once it is imported into the database?

  No. Once a Wasm binary is imported into the database, it's not possible to see the binary data, it can only be executed. Hence, you can only reverse engineer the Wasm binary behaviorally and not by disassembling the binary.

• What happens when a Wasm function crashes or runs out of memory?

  If a Wasm function crashes or runs out of memory, it causes the query to fail and returns an error. If possible, the error message may include a stack into the Wasm function.