Getting started

Prerequisites

Build the native library and install it for your Lua version before running any of the examples below. See Overview for the build steps.

Your first program

This program creates an operator against the in-memory service, writes a file, reads it back, and checks its metadata. No credentials needed — paste it into a fresh project and run it as-is.

local opendal = require("opendal")

-- Create an operator against the in-memory service — no credentials needed.
-- Wrap in pcall because mlua raises errors as Lua errors, not (val, err) tuples.
local ok, op = pcall(opendal.operator.new, "memory", {})
if not ok then
    print("failed to create operator:", op)
    os.exit(1)
end

-- Write a string to a path.
local ok, err = pcall(function() op:write("hello.txt", "Hello, World!") end)
if not ok then
    print("write failed:", err)
    os.exit(1)
end

-- Read it back. Returns the content as a Lua string on success.
local ok, data = pcall(function() return op:read("hello.txt") end)
if not ok then
    print("read failed:", data)
    os.exit(1)
end
print("read " .. #data .. " bytes")

-- Inspect metadata.
local ok, meta = pcall(function() return op:stat("hello.txt") end)
if not ok then
    print("stat failed:", meta)
    os.exit(1)
end
print("size = " .. meta:content_length() .. " bytes")

-- Clean up.
local ok, err = pcall(function() op:delete("hello.txt") end)
if not ok then
    print("delete failed:", err)
    os.exit(1)
end

Error handling

All methods raise a Lua error on failure (like error()). They do not return an (result, error) tuple. Use pcall or xpcall to catch errors:

local ok, result = pcall(function() return op:read("missing.txt") end)
if not ok then
    print("error:", result)   -- result holds the error message
end

On success, each method returns its value directly:

• read → string
• write, delete, create_dir, rename → nothing (void)
• stat → metadata table
• is_exist → bool
• content_length → number
• is_file, is_dir → bool

Use a different service

Only the constructor changes; every method is identical across services.

local opendal = require("opendal")

-- In-memory storage — useful for tests; no credentials or paths needed.
local ok, op = pcall(opendal.operator.new, "memory", {})
if not ok then
    print(op)
    return
end
op:write("key", "value")
print(op:read("key"))   -- "value"

For S3, GCS, Azblob, and every other backend, pass the service scheme and its configuration keys. See /services for the full list and the exact key names each service accepts.

Available operations

Errors are raised (not returned). Wrap calls in pcall when you need to handle failures.

Method	Signature	Returns on success
op:read(path)	(string)	string
op:write(path, bytes)	(string, string)	(nothing)
op:delete(path)	(string)	(nothing)
op:stat(path)	(string)	metadata
op:is_exist(path)	(string)	bool
op:rename(src, dst)	(string, string)	(nothing)
op:create_dir(path)	(string)	(nothing)

metadata returned by stat exposes three methods:

Method	Returns on success
meta:content_length()	number
meta:is_file()	bool
meta:is_dir()	bool

Paths are relative to the operator's root. A trailing / denotes a directory (required for create_dir).