Skip to main content
A Transformation is a named Python function stored on the platform, with a typed input / output schema. Create one imperatively with Transformation.new(...) or declaratively with the @Transformation.from_function decorator; run it with run or wire it into a Pipeline as a TransformationNode. Every method has an async sibling prefixed with a. 
from vectorshift import Transformation
from vectorshift.transformation import IOConfig, IOType, TransformationStatus

​
Lifecycle

​
new

Transformation.new(
    name: str,
    description: str = "",
    function_name: str = "",
    inputs: Optional[dict[str, Any]] = None,
    outputs: Optional[dict[str, Any]] = None,
    function: str = "",
) -> Transformation
Create a new transformation. Parameters
​
name
str
required
Display name. Used by from_function and fetch(name=…) as the idempotency key.
​
description
str
default:"''"
What the transformation does.
​
function_name
str
default:"''"
The Python function name defined inside function.
​
inputs
Optional[dict[str, Any]]
default:"None"
Input schema, {name: io_type}. Each value may be a bare IOType / string or an IOConfig. The wire keeps only the io_type.
​
outputs
Optional[dict[str, Any]]
default:"None"
Output schema, same shape as inputs.
​
function
str
default:"''"
The function source as a string. Should return a dict keyed by your output names.
Returns
​
returns
Transformation
The new instance, with .id, .branch_id, and .version populated.

​
save

Transformation.save() -> Transformation
Create the transformation from the instance’s current attributes (the constructor-then-save alternative to new). Populates .id on the instance.

​
fetch

Transformation.fetch(
    id: Optional[str] = None,
    name: Optional[str] = None,
    username: Optional[str] = None,
    org_name: Optional[str] = None,
) -> Transformation
Fetch by id or name (at least one is required). username / org_name disambiguate a shared transformation. Raises TransformationNotFound if nothing matches.

​
list

Transformation.list(
    limit: int = 50,
    offset: int = 0,
    include_shared: bool = False,
    verbose: bool = False,
) -> TransformationList
Paginated list of transformations visible to the API key’s org. Set include_shared=True to include shared ones, verbose=True to populate full TransformationListEntry fields (otherwise only ids come back). Returns a TransformationList.

​
update

Transformation.update(
    name: Any = ...,
    description: Any = ...,
    function_name: Any = ...,
    inputs: Any = ...,
    outputs: Any = ...,
    function: Any = ...,
) -> Transformation
Partial update — only the fields you pass are sent; omitted fields are left untouched (a _UNSET sentinel distinguishes “not supplied” from an explicit None). Mutates the local instance to match. Returns self.

​
delete

Transformation.delete() -> None
Permanently delete the transformation.

​
From a Python function

​
from_function

@Transformation.from_function(
    name: Optional[str] = None,
    description: Optional[str] = None,
    inputs: Optional[dict[str, Any]] = None,
    outputs: Optional[dict[str, Any]] = None,
    defer: bool = False,
)
def my_fn(...): ...
Decorator that turns a Python function into a Transformation. Works with or without parentheses.
  • Source — the function body is captured via inspect.getsource (decorator lines stripped) and stored as function.
  • Name / description — default to the function’s __name__ and docstring.
  • Schema inference — inputs come from parameter type annotations; outputs from the return annotation. A TypedDict return maps each key to its type; a literal return {…} uses its string keys; anything else becomes a single result. Types map via IOType.from_python. Pass explicit inputs= / outputs= to override.
  • Idempotency — by default the decorator fetches by name, and updates only if the source or schema changed, otherwise creates. Returns the resulting Transformation.
  • defer=True — skip the network call and return an unsaved Transformation you can .save() later.
A non-literal dict return with no TypedDict annotation can’t have its keys inferred — the SDK warns and defaults to {"result": any}. Pass outputs= to be explicit.

​
Running

​
run

Transformation.run(inputs: Optional[dict[str, Any]] = None) -> TransformationRunResult
Execute the transformation with the given input values. Blocks on the engine callback. When the instance has a declared inputs schema, input keys are validated against it — unknown keys raise TransformationInvalidSchema before any request is made. A schemaless instance (e.g. one constructed by id without a fetch) skips this check. A failed engine run raises TransformationRunFailed. Returns
​
returns
TransformationRunResult
Typed TransformationRunResult — .status, .outputs (native Python values, unwrapped from the engine’s DataType envelope), and an optional .error.

​
Instance attributes

A Transformation carries: id, name, description, function_name, inputs, outputs, function, branch_id, version.

​
Types

​
IOConfig

A single input / output schema entry. On create / update the wire keeps only io_type; fetch returns the full object.
​
io_type
IOType
required
See IOType.
​
description
str
default:"—"
Optional human description.

​
TransformationRunResult

​
status
TransformationStatus
required
"success" or "failure" — see TransformationStatus.
​
outputs
dict[str, Any]
required
Output values keyed by output name, unwrapped to native Python types.
​
error
str
default:"—"
Present on failure.

​
TransformationListEntry

​
id
str
required
​
name
str
required
​
description
str
required
​
function_name
str
required
​
modified_date
str
required
Plus user_id, org_id, username, email when verbose=True.

​
TransformationList

​
transformations
list[TransformationListEntry]
required
​
offset
int
required
​
limit
int
required
​
total
int
default:"—"

​
Enums

​
IOType

Wire vocabulary for input / output types:
MemberWire valuePython type
ANYanyAny / unannotated
STRINGstringstr
INTint32int
FLOATfloatfloat
BOOLboolbool
LISTvec<any>list
FILEfilevectorshift.File
IOType.from_python(annotation) maps a Python type annotation to the matching member, defaulting to ANY.

​
TransformationStatus

SUCCESS ("success") · FAILURE ("failure")

​
Errors

All subclass TransformationError, which subclasses VectorshiftError.
  • TransformationNotFound — a fetch returned no result.
  • TransformationAmbiguousName — from_function found more than one transformation by name.
  • TransformationRunFailed — a run completed with a failed status; carries .transformation_id and .message.
  • TransformationInvalidSchema — wrong keys, unknown io_type, or unknown input keys passed to run.
  • TransformationCompileError — the engine refused the Python source.
See the top-level Errors page for the broader hierarchy.

​
What’s next

Overview

Mental model and quick start.

Run & I/O types

Typed inputs, run results, and IOType mapping.

Pipeline node

Wire a Transformation into a Pipeline.