pyspiral 0.5.0__cp310-abi3-macosx_11_0_arm64.whl → 0.6.1__cp310-abi3-macosx_11_0_arm64.whl

spiral/cli/login.py

@@ -1,22 +1,21 @@
 import jwt
-from rich import print
 
-from spiral.cli import state
+from spiral.cli import CONSOLE, state
 
 
 def command(org_id: str | None = None, force: bool = False):
     token = state.settings.device_code_auth.authenticate(force=force, org_id=org_id)
-    print("Successfully logged in.")
-    print(token.expose_secret())
+    CONSOLE.print("Successfully logged in.")
+    CONSOLE.print(token.expose_secret(), soft_wrap=True)
 
 
 def whoami():
     """Display the current user's information."""
     payload = jwt.decode(state.settings.authn.token().expose_secret(), options={"verify_signature": False})
-    print(f"{payload['org_id']}")
-    print(f"{payload['sub']}")
+    CONSOLE.print(f"{payload['org_id']}")
+    CONSOLE.print(f"{payload['sub']}")
 
 
 def logout():
     state.settings.device_code_auth.logout()
-    print("Logged out.")
+    CONSOLE.print("Logged out.")

spiral/cli/orgs.py

@@ -2,13 +2,12 @@ import webbrowser
 from typing import Annotated
 
 import jwt
-import rich
 import typer
 from rich.table import Table
 from typer import Option
 
 from spiral.api.organizations import CreateOrgRequest, InviteUserRequest, OrgRole, PortalLinkIntent, PortalLinkRequest
-from spiral.cli import AsyncTyper, state
+from spiral.cli import CONSOLE, ERR_CONSOLE, AsyncTyper, state
 from spiral.cli.types import OrganizationArg
 
 app = AsyncTyper(short_help="Org admin.")
@@ -17,7 +16,7 @@ app = AsyncTyper(short_help="Org admin.")
 @app.command(help="Switch the active organization.")
 def switch(org_id: OrganizationArg):
     state.settings.device_code_auth.authenticate(org_id=org_id)
-    rich.print(f"Switched to organization: {org_id}")
+    CONSOLE.print(f"Switched to organization: {org_id}")
 
 
 @app.command(help="Create a new organization.")
@@ -29,7 +28,7 @@ def create(
     # Authenticate to the new organization
     state.settings.device_code_auth.authenticate(org_id=res.org.id)
 
-    rich.print(f"{res.org.name} [dim]{res.org.id}[/dim]")
+    CONSOLE.print(f"{res.org.name} [dim]{res.org.id}[/dim]")
 
 
 @app.command(help="List organizations.")
@@ -40,7 +39,7 @@ def ls():
     for m in state.settings.api.organization.list_memberships():
         table.add_row("👉" if m.org.id == org_id else "", m.org.id, m.org.name, m.role)
 
-    rich.print(table)
+    CONSOLE.print(table)
 
 
 @app.command(help="Invite a user to the organization.")
@@ -48,7 +47,7 @@ def invite(email: str, role: OrgRole = OrgRole.MEMBER, expires_in_days: int = 7)
     state.settings.api.organization.invite_user(
         InviteUserRequest(email=email, role=role, expires_in_days=expires_in_days)
     )
-    rich.print(f"Invited {email} as a {role.value}.")
+    CONSOLE.print(f"Invited {email} as a {role.value}.")
 
 
 @app.command(help="Configure single sign-on for your organization.")
@@ -78,7 +77,7 @@ def domains():
 
 def _do_action(intent: PortalLinkIntent):
     res = state.settings.api.organization.portal_link(PortalLinkRequest(intent=intent))
-    rich.print(f"Opening the configuration portal:\n{res.url}")
+    CONSOLE.print(f"Opening the configuration portal:\n{res.url}")
     webbrowser.open(res.url)
 
 
@@ -86,5 +85,5 @@ def current_org_id():
     if token := state.settings.authn.token():
         if org_id := jwt.decode(token.expose_secret(), options={"verify_signature": False}).get("org_id"):
             return org_id
-    rich.print("[red]You are not logged in to an organization.[/red]")
+    ERR_CONSOLE.print("You are not logged in to an organization.")
     raise typer.Exit(1)

spiral/cli/printer.py

@@ -2,14 +2,14 @@ import json
 from collections.abc import Iterable
 from typing import TypeVar
 
-import betterproto
+import betterproto2
 from pydantic import BaseModel
 from rich.console import ConsoleRenderable, Group
 from rich.padding import Padding
 from rich.pretty import Pretty
 from rich.table import Table
 
-T = TypeVar("T", bound=betterproto.Message)
+T = TypeVar("T", bound=betterproto2.Message)
 M = TypeVar("M", bound=BaseModel)
 
 
@@ -34,7 +34,7 @@ def table_of_protos(cls: type[T], messages: Iterable[T], fields: list[str] = Non
 
     TODO(ngates): add a CLI switch to emit JSON results instead of tables.
     """
-    cols = fields or cls()._betterproto.sorted_field_names
+    cols = fields or cls()._betterproto2.sorted_field_names
     table = Table(*cols, title=title or f"{cls.__name__}s")
     for msg in messages:
         table.add_row(*[getattr(msg, col, "") for col in cols])

spiral/cli/projects.py

@@ -1,6 +1,5 @@
 from typing import Annotated
 
-import rich
 import typer
 from typer import Option
 
@@ -19,7 +18,7 @@ from spiral.api.projects import (
     Project,
     WorkloadPrincipalConditions,
 )
-from spiral.cli import AsyncTyper, printer, state
+from spiral.cli import CONSOLE, AsyncTyper, printer, state
 from spiral.cli.types import ProjectArg
 
 app = AsyncTyper(short_help="Projects and grants.")
@@ -28,7 +27,7 @@ app = AsyncTyper(short_help="Projects and grants.")
 @app.command(help="List projects.")
 def ls():
     projects = list(state.settings.api.project.list())
-    rich.print(printer.table_of_models(Project, projects))
+    CONSOLE.print(printer.table_of_models(Project, projects))
 
 
 @app.command(help="Create a new project.")
@@ -39,7 +38,7 @@ def create(
     name: Annotated[str | None, Option(help="Friendly name for the project.")] = None,
 ):
     res = state.settings.api.project.create(CreateProjectRequest(id_prefix=id_prefix, name=name))
-    rich.print(f"Created project {res.project.id}")
+    CONSOLE.print(f"Created project {res.project.id}")
 
 
 @app.command(help="Grant a role on a project.")
@@ -127,10 +126,10 @@ def grant(
         ),
     )
 
-    rich.print(f"Granted role {role} on project {project}")
+    CONSOLE.print(f"Granted role {role} on project {project}")
 
 
 @app.command(help="List project grants.")
 def grants(project: ProjectArg):
     project_grants = list(state.settings.api.project.list_grants(project))
-    rich.print(printer.table_of_models(Grant, project_grants, title="Project Grants"))
+    CONSOLE.print(printer.table_of_models(Grant, project_grants, title="Project Grants"))

spiral/cli/tables.py

@@ -0,0 +1,131 @@
+from typing import Annotated
+
+import questionary
+import rich
+import rich.table
+import typer
+from questionary import Choice
+from typer import Argument, Option
+
+from spiral import Spiral
+from spiral.api.projects import TableResource
+from spiral.cli import CONSOLE, ERR_CONSOLE, AsyncTyper, state
+from spiral.cli.types import ProjectArg
+from spiral.debug.manifests import display_manifests
+from spiral.table import Table
+
+app = AsyncTyper(short_help="Spiral Tables.")
+
+
+def ask_table(project_id: str, title: str = "Select a table") -> str:
+    tables: list[TableResource] = list(state.spiral.project(project_id).list_tables())
+
+    if not tables:
+        ERR_CONSOLE.print("No tables found")
+        raise typer.Exit(1)
+
+    return questionary.select(  # pyright: ignore[reportAny]
+        title,
+        choices=[
+            Choice(title=f"{table.dataset}.{table.table}", value=f"{table.dataset}.{table.table}")
+            for table in sorted(tables, key=lambda t: (t.dataset, t.table))
+        ],
+    ).ask()
+
+
+def get_table(
+    project: ProjectArg,
+    table: Annotated[str | None, Option(help="Table name.")] = None,
+    dataset: Annotated[str | None, Option(help="Dataset name.")] = None,
+) -> tuple[str, Table]:
+    if table is None:
+        identifier = ask_table(project)
+    else:
+        identifier = table
+        if dataset is not None:
+            identifier = f"{dataset}.{table}"
+    return identifier, state.spiral.project(project).table(identifier)
+
+
+@app.command(help="List tables.")
+def ls(
+    project: ProjectArg,
+):
+    tables = Spiral().project(project).list_tables()
+
+    rich_table = rich.table.Table("id", "dataset", "name", title="Spiral tables")
+    for table in tables:
+        rich_table.add_row(table.id, table.dataset, table.table)
+    CONSOLE.print(rich_table)
+
+
+@app.command(help="Show the table key schema.")
+def key_schema(
+    project: ProjectArg,
+    table: Annotated[str | None, Option(help="Table name.")] = None,
+    dataset: Annotated[str | None, Option(help="Dataset name.")] = None,
+):
+    _, t = get_table(project, table, dataset)
+    CONSOLE.print(t.key_schema)
+
+
+@app.command(help="Compute the full table schema.")
+def schema(
+    project: ProjectArg,
+    table: Annotated[str | None, Option(help="Table name.")] = None,
+    dataset: Annotated[str | None, Option(help="Dataset name.")] = None,
+):
+    _, t = get_table(project, table, dataset)
+    CONSOLE.print(t.schema())
+
+
+@app.command(help="Flush Write-Ahead-Log.")
+def flush(
+    project: ProjectArg,
+    table: Annotated[str | None, Option(help="Table name.")] = None,
+    dataset: Annotated[str | None, Option(help="Dataset name.")] = None,
+):
+    identifier, t = get_table(project, table, dataset)
+    state.spiral._ops().flush_wal(t.core)  # pyright: ignore[reportPrivateUsage]
+    CONSOLE.print(f"Flushed WAL for table {identifier} in project {project}.")
+
+
+@app.command(help="Display scan.")
+def debug(
+    project: ProjectArg,
+    table: Annotated[str | None, Option(help="Table name.")] = None,
+    dataset: Annotated[str | None, Option(help="Dataset name.")] = None,
+    column_group: Annotated[str, Argument(help="Dot-separated column group path.")] = ".",
+):
+    _, t = get_table(project, table, dataset)
+    scan = state.spiral.scan(t[column_group] if column_group != "." else t)
+    scan._debug()  # pyright: ignore[reportPrivateUsage]
+
+
+@app.command(help="Display all manifests.")
+def manifests(
+    project: ProjectArg,
+    table: Annotated[str | None, Option(help="Table name.")] = None,
+    dataset: Annotated[str | None, Option(help="Dataset name.")] = None,
+):
+    _, t = get_table(project, table, dataset)
+    s = t.snapshot()
+
+    key_space_state = state.spiral._ops().key_space_state(s.core)  # pyright: ignore[reportPrivateUsage]
+    key_space_manifest = key_space_state.manifest
+
+    column_groups_states = state.spiral._ops().column_groups_states(s.core, key_space_state)  # pyright: ignore[reportPrivateUsage]
+
+    display_manifests(key_space_manifest, [(x.column_group, x.manifest) for x in column_groups_states])
+
+
+@app.command(help="Display the manifests which would be read by a scan of the given column group.")
+def scan_manifests(
+    project: ProjectArg,
+    table: Annotated[str | None, Option(help="Table name.")] = None,
+    dataset: Annotated[str | None, Option(help="Dataset name.")] = None,
+    column_group: Annotated[str, Argument(help="Dot-separated column group path.")] = ".",
+):
+    _, t = get_table(project, table, dataset)
+    scan = state.spiral.scan(t[column_group] if column_group != "." else t)
+    scan._dump_manifests()  # pyright: ignore[reportPrivateUsage]

spiral/cli/telemetry.py

@@ -1,8 +1,7 @@
 import pyperclip
-import rich
 
 from spiral.api.telemetry import IssueExportTokenResponse
-from spiral.cli import AsyncTyper, state
+from spiral.cli import CONSOLE, AsyncTyper, state
 
 app = AsyncTyper(short_help="Client-side telemetry.")
 
@@ -14,5 +13,5 @@ def export():
     command = f"export SPIRAL_OTEL_TOKEN={res.token}"
     pyperclip.copy(command)
 
-    rich.print("Export command copied to clipboard! Paste and run to set [green]SPIRAL_OTEL_TOKEN[/green].")
-    rich.print("[dim]Token is valid for 1h.[/dim]")
+    CONSOLE.print("Export command copied to clipboard! Paste and run to set [green]SPIRAL_OTEL_TOKEN[/green].")
+    CONSOLE.print("[dim]Token is valid for 1h.[/dim]")

spiral/cli/text.py

@@ -0,0 +1,115 @@
+from typing import Annotated
+
+import questionary
+import rich
+import typer
+from questionary import Choice
+from typer import Option
+
+from spiral.api.projects import TextIndexResource
+from spiral.api.text_indexes import CreateWorkerRequest, SyncIndexRequest
+from spiral.api.types import IndexId
+from spiral.api.workers import CPU, GcpRegion, Memory, ResourceClass
+from spiral.cli import CONSOLE, ERR_CONSOLE, AsyncTyper, state
+from spiral.cli.types import ProjectArg
+
+app = AsyncTyper(short_help="Text Indexes.")
+
+
+def ask_index(project_id, title="Select an index"):
+    indexes: list[TextIndexResource] = list(state.spiral.project(project_id).list_text_indexes())
+
+    if not indexes:
+        ERR_CONSOLE.print("No indexes found")
+        raise typer.Exit(1)
+
+    return questionary.select(
+        title,
+        choices=[Choice(title=index.name, value=index.id) for index in sorted(indexes, key=lambda t: (t.name, t.id))],
+    ).ask()
+
+
+def get_index_id(
+    project: ProjectArg,
+    name: Annotated[str | None, Option(help="Index name.")] = None,
+) -> IndexId:
+    if name is None:
+        return ask_index(project)
+
+    indexes: list[TextIndexResource] = list(state.spiral.project(project).list_text_indexes())
+    for index in indexes:
+        if index.name == name:
+            return index.id
+    raise ValueError(f"Index not found: {name}")
+
+
+@app.command(help="List indexes.")
+def ls(
+    project: ProjectArg,
+):
+    """List indexes."""
+    indexes = state.spiral.project(project).list_text_indexes()
+
+    rich_table = rich.table.Table("id", "name", title="Text Indexes")
+    for index in indexes:
+        rich_table.add_row(index.id, index.name)
+    CONSOLE.print(rich_table)
+
+
+@app.command(help="Trigger a sync job for an index.")
+def sync(
+    project: ProjectArg,
+    name: Annotated[str | None, Option(help="Index name.")] = None,
+    resources: Annotated[ResourceClass, Option(help="Resources to use for the sync job.")] = ResourceClass.SMALL,
+):
+    """Trigger a sync job."""
+    index_id = get_index_id(project, name)
+    response = state.spiral.api.text_indexes.sync_index(index_id, SyncIndexRequest(resources=resources))
+    CONSOLE.print(f"Triggered sync job {response.worker_id} for index {index_id}.")
+
+
+@app.command(name="serve", help="Spin up a worker to serve an index.")
+def serve(
+    project: ProjectArg,
+    index: Annotated[str | None, Option(help="Index name.")] = None,
+    region: Annotated[GcpRegion, Option(help="GCP region for the worker.")] = GcpRegion.US_EAST4,
+    cpu: Annotated[CPU, Option(help="CPU resources for the worker.")] = CPU.ONE,
+    memory: Annotated[Memory, Option(help="Memory resources for the worker in MB.")] = Memory.MB_512,
+):
+    """Spin up a worker."""
+    index_id = get_index_id(project, index)
+    request = CreateWorkerRequest(cpu=cpu, memory=memory, region=region)
+    response = state.spiral.api.text_indexes.create_worker(index_id, request)
+    CONSOLE.print(f"Created worker {response.worker_id} for {index_id}.")
+
+
+@app.command(name="workers", help="List search workers.")
+def workers(
+    project: ProjectArg,
+    index: Annotated[str | None, Option(help="Index name.")] = None,
+):
+    """List text search workers."""
+    index_id = get_index_id(project, index)
+    worker_ids = state.spiral.api.text_indexes.list_workers(index_id)
+
+    rich_table = rich.table.Table("Worker ID", "URL", title=f"Text Search Workers for {index_id}")
+    for worker_id in worker_ids:
+        try:
+            worker = state.spiral.api.text_indexes.get_worker(worker_id)
+            rich_table.add_row(
+                worker_id,
+                worker.url,
+            )
+        except Exception:
+            rich_table.add_row(
+                worker_id,
+                "Unavailable",
+            )
+    CONSOLE.print(rich_table)
+
+
+@app.command(name="shutdown", help="Shutdown a search worker.")
+def shutdown(worker_id: str):
+    """Shutdown a worker."""
+    state.spiral.api.text_indexes.shutdown_worker(worker_id)
+    CONSOLE.print(f"Requested worker {worker_id} to shutdown.")

spiral/cli/types.py

@@ -1,20 +1,19 @@
 from typing import Annotated
 
 import questionary
-import rich
 import typer
 from questionary import Choice
 from typer import Argument
 
 from spiral.api.types import OrgId, ProjectId
-from spiral.cli import state
+from spiral.cli import ERR_CONSOLE, state
 
 
 def ask_project(title="Select a project"):
     projects = list(state.settings.api.project.list())
 
     if not projects:
-        rich.print("[red]No projects found[/red]")
+        ERR_CONSOLE.print("No projects found")
         raise typer.Exit(1)
 
     return questionary.select(
@@ -33,7 +32,7 @@ def _org_default():
     memberships = list(state.settings.api.organization.list_memberships())
 
     if not memberships:
-        rich.print("[red]No organizations found[/red]")
+        ERR_CONSOLE.print("No organizations found")
         raise typer.Exit(1)
 
     return questionary.select(

spiral/cli/workloads.py

@@ -2,12 +2,11 @@ from typing import Annotated
 
 import pyperclip
 import questionary
-import rich
 from questionary import Choice
 from typer import Argument, Option
 
 from spiral.api.workloads import CreateWorkloadRequest, IssueWorkloadCredentialsResponse, Workload
-from spiral.cli import AsyncTyper, printer, state
+from spiral.cli import CONSOLE, ERR_CONSOLE, AsyncTyper, printer, state
 from spiral.cli.types import ProjectArg
 
 app = AsyncTyper()
@@ -19,7 +18,7 @@ def create(
     name: Annotated[str | None, Option(help="Friendly name for the workload.")] = None,
 ):
     res = state.settings.api.workload.create(project, CreateWorkloadRequest(name=name))
-    rich.print(f"Created workload {res.workload.id}")
+    CONSOLE.print(f"Created workload {res.workload.id}")
 
 
 @app.command(help="List workloads.")
@@ -27,7 +26,7 @@ def ls(
     project: ProjectArg,
 ):
     workloads = list(state.settings.api.workload.list(project))
-    rich.print(printer.table_of_models(Workload, workloads, fields=["id", "project_id", "name"]))
+    CONSOLE.print(printer.table_of_models(Workload, workloads, fields=["id", "project_id", "name"]))
 
 
 @app.command(help="Issue new workflow credentials.")
@@ -46,14 +45,14 @@ def issue_credentials(workload_id: Annotated[str, Argument(help="Workload ID.")]
 
         if choice == 1:
             pyperclip.copy(res.client_secret)
-            rich.print("[green]Secret copied to clipboard![/green]")
+            CONSOLE.print("[green]Secret copied to clipboard![/green]")
             break
         elif choice == 2:
-            rich.print(f"[green]Token Secret:[/green] {res.client_secret}")
+            CONSOLE.print(f"[green]Token Secret:[/green] {res.client_secret}")
             break
         elif choice == 3:
             break
         else:
-            rich.print("[red]Invalid choice. Please try again.[/red]")
+            ERR_CONSOLE.print("Invalid choice. Please try again.")
 
-    rich.print(f"[green]Token ID:[/green] {res.client_id}")
+    CONSOLE.print(f"[green]Token ID:[/green] {res.client_id}")

spiral/client.py

@@ -1,24 +1,29 @@
+from datetime import datetime, timedelta
 from typing import TYPE_CHECKING
 
 import jwt
+import pyarrow as pa
 
 from spiral.api import SpiralAPI
 from spiral.api.projects import CreateProjectRequest, CreateProjectResponse
+from spiral.core.client import Operations
 from spiral.core.client import Spiral as CoreSpiral
+from spiral.datetime_ import timestamp_micros
+from spiral.expressions import ExprLike
+from spiral.scan import Scan
 from spiral.settings import Settings, settings
 
 if TYPE_CHECKING:
     from spiral.iceberg import Iceberg
+    from spiral.key_space_index import KeySpaceIndex
     from spiral.project import Project
+    from spiral.table import Table
+    from spiral.text_index import TextIndex
 
 
 class Spiral:
     def __init__(self, config: Settings | None = None):
         self._config = config or settings()
-        self._api = self._config.api
-        self._core = CoreSpiral(
-            api_url=self._config.spiraldb.uri, spfs_url=self._config.spfs.uri, authn=self._config.authn
-        )
         self._org = None
 
     @property
@@ -27,7 +32,11 @@ class Spiral:
 
     @property
     def api(self) -> SpiralAPI:
-        return self._api
+        return self._config.api
+
+    @property
+    def _core(self) -> CoreSpiral:
+        return self._config.core
 
     @property
     def organization(self) -> str:
@@ -45,7 +54,7 @@ class Spiral:
         """List project IDs."""
         from .project import Project
 
-        return [Project(self, id=p.id, name=p.name) for p in self.api.project.list()]
+        return [Project(self, project_id=p.id, name=p.name) for p in self.api.project.list()]
 
     def create_project(
         self,
@@ -64,7 +73,102 @@ class Spiral:
         from spiral.project import Project
 
         # We avoid an API call since we'd just be fetching a human-readable name. Seems a waste in most cases.
-        return Project(self, id=project_id, name=project_id)
+        return Project(self, project_id=project_id, name=project_id)
+
+    def table(self, table_id: str) -> "Table":
+        """Open a table using an ID."""
+        from spiral.table import Table
+
+        return Table(self, self._core.table(table_id))
+
+    def text_index(self, index_id: str) -> "TextIndex":
+        """Open a text index using an ID."""
+        from spiral.text_index import TextIndex
+
+        return TextIndex(self._core.text_index(index_id))
+
+    def key_space_index(self, index_id: str) -> "KeySpaceIndex":
+        """Open a key space index using an ID."""
+        from spiral.key_space_index import KeySpaceIndex
+
+        return KeySpaceIndex(self._core.key_space_index(index_id))
+
+    def scan(
+        self,
+        *projections: ExprLike,
+        where: ExprLike | None = None,
+        asof: datetime | int | None = None,
+        exclude_keys: bool = False,
+    ) -> Scan:
+        """Starts a read transaction on the Spiral.
+
+        Args:
+            projections: a set of expressions that return struct arrays.
+            where: a query expression to apply to the data.
+            asof: only data written before the given timestamp will be returned, caveats around compaction.
+            exclude_keys: whether to exclude the key columns in the scan result, defaults to False.
+                Note that if a projection includes a key column, it will be included in the result.
+        """
+        from spiral import expressions as se
+
+        if isinstance(asof, datetime):
+            asof = timestamp_micros(asof)
+
+        # Combine all projections into a single struct.
+        projection = se.merge(*projections)
+        if where is not None:
+            where = se.lift(where)
+
+        return Scan(
+            self._core.scan(
+                projection.__expr__,
+                filter=where.__expr__ if where else None,
+                asof=asof,
+                exclude_keys=exclude_keys,
+            ),
+        )
+
+    # TODO(marko): This should be query, and search should be query + scan.
+    def search(
+        self,
+        top_k: int,
+        *rank_by: ExprLike,
+        filters: ExprLike | None = None,
+        freshness_window: timedelta | None = None,
+    ) -> pa.RecordBatchReader:
+        """Queries the index with the given rank by and filters clauses. Returns a steam of scored keys.
+
+        Args:
+            top_k: The number of top results to return.
+            rank_by: Rank by expressions are combined for scoring.
+                See `se.text.find` and `se.text.boost` for scoring expressions.
+            filters: The `filters` expression is used to filter the results.
+                It must return a boolean value and use only conjunctions (ANDs). Expressions in filters
+                statement are considered either a `must` or `must_not` clause in search terminology.
+            freshness_window: If provided, the index will not be refreshed if its freshness does not exceed this window.
+        """
+        from spiral import expressions as se
+
+        if not rank_by:
+            raise ValueError("At least one rank by expression is required.")
+        rank_by = se.or_(*rank_by)
+        if filters is not None:
+            filters = se.lift(filters)
+
+        if freshness_window is None:
+            freshness_window = timedelta(seconds=0)
+        freshness_window_s = int(freshness_window.total_seconds())
+
+        return self._core.search(
+            top_k=top_k,
+            rank_by=rank_by.__expr__,
+            filters=filters.__expr__ if filters else None,
+            freshness_window_s=freshness_window_s,
+        )
+
+    def _ops(self) -> Operations:
+        """Access maintenance operations."""
+        return self._core._ops(format=settings().file_format)
 
     @property
     def iceberg(self) -> "Iceberg":
@@ -72,7 +176,6 @@ class Spiral:
         Apache Iceberg is a powerful open-source table format designed for high-performance data lakes.
         Iceberg brings reliability, scalability, and advanced features like time travel, schema evolution,
         and ACID transactions to your warehouse.
-
         """
         from spiral.iceberg import Iceberg