Skip to content

Get started on AWS

On AWS, a CloudFormation stack in your AWS account lets Polars Nanook start and stop EC2 instances on demand. Connect your AWS account to a workspace in two steps, then run a first remote query. Before you start, install the client and sign up.

The stack is deployed in the AWS account you are logged in to in your browser. If your company uses SSO, log in through your company's AWS portal first.

Open Integrations > Infrastructure in the portal sidebar and click Connect on the Amazon Web Services card. The Link your AWS account step offers three ways to deploy the stack:

  • Use Deploy to AWS to open the CloudFormation quick-create page in your browser.
  • Use Deploy to AWS in an existing VPC to deploy into a VPC you already have (see Set up AWS).
  • Use Copy the setup link to get the deployment URL and share it with your operations team or AWS administrator. They can deploy it without a Polars Nanook account.

nanook workspace aws connect opens the same CloudFormation quick-create page in your browser and waits until the workspace is connected:

nanook workspace aws connect --workspace-name "My workspace"

Step 2: Deploy the CloudFormation stack

The quick-create page is pre-filled with the template and a stack name derived from your workspace name, so with Deploy to AWS you don't have to change anything. With Deploy to AWS in an existing VPC, also select the VPC and its public subnets.

Scroll to the bottom of the page, check the acknowledgment that the template creates IAM resources, and click Create stack.

AWS CloudFormation IAM capabilities acknowledgment before creating the stack

The Deploy CloudFormation stack step in the portal tracks the deployment until it shows Connected, typically within 5 minutes. If a step fails, see Error messages.

Step 3: Run a test query

With the workspace connected, a compute context describes the hardware Polars Nanook starts for a query:

ComputeContext · LazyFrameRemote

import polars as pl
import polars_nanook as pn

pn.authenticate()

# Start one t4g.small instance in the AWS account connected to the workspace.
ctx = pn.ComputeContext(workspace="My workspace", instance_type="t4g.small")

# A regular lazy Polars query; `.remote(ctx)` runs it on that instance.
result = (
    pl.LazyFrame({"a": [1, 2, 3], "b": [4, 4, 5]})
    .with_columns(pl.col("a").max().over("b").alias("c"))
    .remote(ctx)
    .collect()
)

print(result)
Output
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 4   ┆ 2   │
│ 2   ┆ 4   ┆ 2   │
│ 3   ┆ 5   ┆ 3   │
└─────┴─────┴─────┘

.collect() streams the result back to the client. The portal detects the query and lists it under Queries, together with its compute and its profile. The instance stops after the workspace's idle timeout, which is 60 minutes unless a workspace admin changes it.

Next steps