feat(datatables): take the sdk role as an options argument

cli/src/guidance/skills.gen.ts

@@ -1102,8 +1102,8 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
 /**
  * Create a SQL template function for PostgreSQL/datatable queries
  * @param name - Database/datatable name (default: "main")
- * @param role - Data table role to run as, on a datatable with permissions
- *               enabled (default: the data table's default role)
+ * @param opts - Optional settings; \`role\` runs the query as that data table
+ *               role (default: the data table's default role)
  * @returns SQL template function for building parameterized queries
  * @example
  * let sql = wmill.datatable()
@@ -1113,8 +1113,10 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
  *   SELECT * FROM friends
  *     WHERE name = \${name} AND age = \${age}::int
  * \`.fetch()
+ * @example
+ * let sql = wmill.datatable('main', { role: 'operator' })
  */
-datatable(name: string = "main", role?: string): DatatableSqlTemplateFunction
+datatable(name: string = "main", opts?: DatatableOptions): DatatableSqlTemplateFunction
 
 /**
  * Create a SQL template function for DuckDB/ducklake queries
@@ -1887,8 +1889,8 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
 /**
  * Create a SQL template function for PostgreSQL/datatable queries
  * @param name - Database/datatable name (default: "main")
- * @param role - Data table role to run as, on a datatable with permissions
- *               enabled (default: the data table's default role)
+ * @param opts - Optional settings; \`role\` runs the query as that data table
+ *               role (default: the data table's default role)
  * @returns SQL template function for building parameterized queries
  * @example
  * let sql = wmill.datatable()
@@ -1898,8 +1900,10 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
  *   SELECT * FROM friends
  *     WHERE name = \${name} AND age = \${age}::int
  * \`.fetch()
+ * @example
+ * let sql = wmill.datatable('main', { role: 'operator' })
  */
-datatable(name: string = "main", role?: string): DatatableSqlTemplateFunction
+datatable(name: string = "main", opts?: DatatableOptions): DatatableSqlTemplateFunction
 
 /**
  * Create a SQL template function for DuckDB/ducklake queries
@@ -2766,8 +2770,8 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
 /**
  * Create a SQL template function for PostgreSQL/datatable queries
  * @param name - Database/datatable name (default: "main")
- * @param role - Data table role to run as, on a datatable with permissions
- *               enabled (default: the data table's default role)
+ * @param opts - Optional settings; \`role\` runs the query as that data table
+ *               role (default: the data table's default role)
  * @returns SQL template function for building parameterized queries
  * @example
  * let sql = wmill.datatable()
@@ -2777,8 +2781,10 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
  *   SELECT * FROM friends
  *     WHERE name = \${name} AND age = \${age}::int
  * \`.fetch()
+ * @example
+ * let sql = wmill.datatable('main', { role: 'operator' })
  */
-datatable(name: string = "main", role?: string): DatatableSqlTemplateFunction
+datatable(name: string = "main", opts?: DatatableOptions): DatatableSqlTemplateFunction
 
 /**
  * Create a SQL template function for DuckDB/ducklake queries

python-client/wmill/wmill/client.py

@@ -1408,7 +1408,7 @@ class Windmill:
             },
         )
 
-    def datatable(self, name: str = "main", role: Optional[str] = None):
+    def datatable(self, name: str = "main", *, role: Optional[str] = None):
         """Get a DataTable client for SQL queries.
 
         Args:
@@ -2242,7 +2242,7 @@ def username_to_email(username: str) -> str:
 
 
 @init_global_client
-def datatable(name: str = "main", role: Optional[str] = None) -> DataTableClient:
+def datatable(name: str = "main", *, role: Optional[str] = None) -> DataTableClient:
     """Get a DataTable client for SQL queries.
 
     Args:
@@ -2252,8 +2252,11 @@ def datatable(name: str = "main", role: Optional[str] = None) -> DataTableClient
 
     Returns:
         DataTableClient instance
+
+    Example:
+        wmill.datatable("main", role="operator")
     """
-    return _client.datatable(name, role)
+    return _client.datatable(name, role=role)
 
 @init_global_client
 def ducklake(name: str = "main") -> DucklakeClient:

system_prompts/auto-generated/prompts.ts

@@ -1800,8 +1800,8 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
 /**
  * Create a SQL template function for PostgreSQL/datatable queries
  * @param name - Database/datatable name (default: "main")
- * @param role - Data table role to run as, on a datatable with permissions
- *               enabled (default: the data table's default role)
+ * @param opts - Optional settings; \`role\` runs the query as that data table
+ *               role (default: the data table's default role)
  * @returns SQL template function for building parameterized queries
  * @example
  * let sql = wmill.datatable()
@@ -1811,8 +1811,10 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
  *   SELECT * FROM friends
  *     WHERE name = \${name} AND age = \${age}::int
  * \`.fetch()
+ * @example
+ * let sql = wmill.datatable('main', { role: 'operator' })
  */
-datatable(name: string = "main", role?: string): DatatableSqlTemplateFunction
+datatable(name: string = "main", opts?: DatatableOptions): DatatableSqlTemplateFunction
 
 /**
  * Create a SQL template function for DuckDB/ducklake queries
@@ -2968,8 +2970,8 @@ interface DatatableSqlTemplateFunction {
 
 Create a SQL template function for PostgreSQL/datatable queries
 @param name - Database/datatable name (default: "main")
-@param role - Data table role to run as, on a datatable with permissions
-              enabled (default: the data table's default role)
+@param opts - Optional settings; \`role\` runs the query as that data table
+              role (default: the data table's default role)
 @returns SQL template function for building parameterized queries
 @example
 let sql = wmill.datatable()
@@ -2979,9 +2981,11 @@ await sql\`
   SELECT * FROM friends
     WHERE name = \${name} AND age = \${age}::int
 \`.fetch()
+@example
+let sql = wmill.datatable('main', { role: 'operator' })
 \`\`\`typescript
 function datatable(name: string = "main",
-  role?: string): DatatableSqlTemplateFunction
+  opts?: DatatableOptions): DatatableSqlTemplateFunction
 \`\`\`
 `;
 
@@ -2998,6 +3002,9 @@ Import: \`import wmill\`
 # 
 # Returns:
 #     DataTableClient instance
+# 
+# Example:
+#     wmill.datatable("main", role="operator")
 def datatable(name: str = 'main', role: Optional[str] = None) -> DataTableClient
 
 # Client for executing SQL queries against Windmill DataTables.

system_prompts/auto-generated/script.md

@@ -1992,8 +1992,8 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
 /**
  * Create a SQL template function for PostgreSQL/datatable queries
  * @param name - Database/datatable name (default: "main")
- * @param role - Data table role to run as, on a datatable with permissions
- *               enabled (default: the data table's default role)
+ * @param opts - Optional settings; `role` runs the query as that data table
+ *               role (default: the data table's default role)
  * @returns SQL template function for building parameterized queries
  * @example
  * let sql = wmill.datatable()
@@ -2003,8 +2003,10 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
  *   SELECT * FROM friends
  *     WHERE name = ${name} AND age = ${age}::int
  * `.fetch()
+ * @example
+ * let sql = wmill.datatable('main', { role: 'operator' })
  */
-datatable(name: string = "main", role?: string): DatatableSqlTemplateFunction
+datatable(name: string = "main", opts?: DatatableOptions): DatatableSqlTemplateFunction
 
 /**
  * Create a SQL template function for DuckDB/ducklake queries

system_prompts/auto-generated/sdks/datatable-python.md

@@ -11,6 +11,9 @@ Import: `import wmill`
 # 
 # Returns:
 #     DataTableClient instance
+# 
+# Example:
+#     wmill.datatable("main", role="operator")
 def datatable(name: str = 'main', role: Optional[str] = None) -> DataTableClient
 
 # Client for executing SQL queries against Windmill DataTables.

system_prompts/auto-generated/sdks/datatable-typescript.md

@@ -62,8 +62,8 @@ interface DatatableSqlTemplateFunction {
 
 Create a SQL template function for PostgreSQL/datatable queries
 @param name - Database/datatable name (default: "main")
-@param role - Data table role to run as, on a datatable with permissions
-              enabled (default: the data table's default role)
+@param opts - Optional settings; `role` runs the query as that data table
+              role (default: the data table's default role)
 @returns SQL template function for building parameterized queries
 @example
 let sql = wmill.datatable()
@@ -73,7 +73,9 @@ await sql`
   SELECT * FROM friends
     WHERE name = ${name} AND age = ${age}::int
 `.fetch()
+@example
+let sql = wmill.datatable('main', { role: 'operator' })
 ```typescript
 function datatable(name: string = "main",
-  role?: string): DatatableSqlTemplateFunction
+  opts?: DatatableOptions): DatatableSqlTemplateFunction
 ```

system_prompts/auto-generated/sdks/typescript.md

@@ -557,8 +557,8 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
 /**
  * Create a SQL template function for PostgreSQL/datatable queries
  * @param name - Database/datatable name (default: "main")
- * @param role - Data table role to run as, on a datatable with permissions
- *               enabled (default: the data table's default role)
+ * @param opts - Optional settings; `role` runs the query as that data table
+ *               role (default: the data table's default role)
  * @returns SQL template function for building parameterized queries
  * @example
  * let sql = wmill.datatable()
@@ -568,8 +568,10 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
  *   SELECT * FROM friends
  *     WHERE name = ${name} AND age = ${age}::int
  * `.fetch()
+ * @example
+ * let sql = wmill.datatable('main', { role: 'operator' })
  */
-datatable(name: string = "main", role?: string): DatatableSqlTemplateFunction
+datatable(name: string = "main", opts?: DatatableOptions): DatatableSqlTemplateFunction
 
 /**
  * Create a SQL template function for DuckDB/ducklake queries

system_prompts/auto-generated/skills/write-script-bun/SKILL.md

@@ -728,8 +728,8 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
 /**
  * Create a SQL template function for PostgreSQL/datatable queries
  * @param name - Database/datatable name (default: "main")
- * @param role - Data table role to run as, on a datatable with permissions
- *               enabled (default: the data table's default role)
+ * @param opts - Optional settings; `role` runs the query as that data table
+ *               role (default: the data table's default role)
  * @returns SQL template function for building parameterized queries
  * @example
  * let sql = wmill.datatable()
@@ -739,8 +739,10 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
  *   SELECT * FROM friends
  *     WHERE name = ${name} AND age = ${age}::int
  * `.fetch()
+ * @example
+ * let sql = wmill.datatable('main', { role: 'operator' })
  */
-datatable(name: string = "main", role?: string): DatatableSqlTemplateFunction
+datatable(name: string = "main", opts?: DatatableOptions): DatatableSqlTemplateFunction
 
 /**
  * Create a SQL template function for DuckDB/ducklake queries

system_prompts/auto-generated/skills/write-script-bunnative/SKILL.md

@@ -728,8 +728,8 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
 /**
  * Create a SQL template function for PostgreSQL/datatable queries
  * @param name - Database/datatable name (default: "main")
- * @param role - Data table role to run as, on a datatable with permissions
- *               enabled (default: the data table's default role)
+ * @param opts - Optional settings; `role` runs the query as that data table
+ *               role (default: the data table's default role)
  * @returns SQL template function for building parameterized queries
  * @example
  * let sql = wmill.datatable()
@@ -739,8 +739,10 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
  *   SELECT * FROM friends
  *     WHERE name = ${name} AND age = ${age}::int
  * `.fetch()
+ * @example
+ * let sql = wmill.datatable('main', { role: 'operator' })
  */
-datatable(name: string = "main", role?: string): DatatableSqlTemplateFunction
+datatable(name: string = "main", opts?: DatatableOptions): DatatableSqlTemplateFunction
 
 /**
  * Create a SQL template function for DuckDB/ducklake queries

system_prompts/auto-generated/skills/write-script-deno/SKILL.md

@@ -730,8 +730,8 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
 /**
  * Create a SQL template function for PostgreSQL/datatable queries
  * @param name - Database/datatable name (default: "main")
- * @param role - Data table role to run as, on a datatable with permissions
- *               enabled (default: the data table's default role)
+ * @param opts - Optional settings; `role` runs the query as that data table
+ *               role (default: the data table's default role)
  * @returns SQL template function for building parameterized queries
  * @example
  * let sql = wmill.datatable()
@@ -741,8 +741,10 @@ parseS3Object(s3Object: S3Object): S3ObjectRecord
  *   SELECT * FROM friends
  *     WHERE name = ${name} AND age = ${age}::int
  * `.fetch()
+ * @example
+ * let sql = wmill.datatable('main', { role: 'operator' })
  */
-datatable(name: string = "main", role?: string): DatatableSqlTemplateFunction
+datatable(name: string = "main", opts?: DatatableOptions): DatatableSqlTemplateFunction
 
 /**
  * Create a SQL template function for DuckDB/ducklake queries

typescript-client/sqlUtils.d.ts

@@ -85,7 +85,10 @@ export interface DatatableSqlTemplateFunction extends SqlTemplateFunction {
   query<T = any>(sql: string, ...params: any[]): SqlStatement<T>;
 }
 
-export declare function datatable(name?: string, role?: string): DatatableSqlTemplateFunction;
+export interface DatatableOptions {
+    role?: string;
+}
+export declare function datatable(name?: string, opts?: DatatableOptions): DatatableSqlTemplateFunction;
 export declare function ducklake(name: string): SqlTemplateFunction;
 
 export interface DucklakeMaterializeOptions {

typescript-client/sqlUtils.ts

@@ -108,6 +108,12 @@ export interface DatatableSqlTemplateFunction extends SqlTemplateFunction {
   query<T = any>(sql: string, ...params: any[]): SqlStatement<T>;
 }
 
+export interface DatatableOptions {
+  /** Data table role to run as, on a data table with permissions enabled.
+   * Omitted means the data table's default role. */
+  role?: string;
+}
+
 // ---------------------------------------------------------------------------
 // Provider interface — captures what differs between datatable and ducklake
 // ---------------------------------------------------------------------------
@@ -332,8 +338,8 @@ function buildSqlTemplateFunction(provider: SqlProvider): SqlTemplateFunction {
 /**
  * Create a SQL template function for PostgreSQL/datatable queries
  * @param name - Database/datatable name (default: "main")
- * @param role - Data table role to run as, on a datatable with permissions
- *               enabled (default: the data table's default role)
+ * @param opts - Optional settings; `role` runs the query as that data table
+ *               role (default: the data table's default role)
  * @returns SQL template function for building parameterized queries
  * @example
  * let sql = wmill.datatable()
@@ -343,13 +349,15 @@ function buildSqlTemplateFunction(provider: SqlProvider): SqlTemplateFunction {
  *   SELECT * FROM friends
  *     WHERE name = ${name} AND age = ${age}::int
  * `.fetch()
+ * @example
+ * let sql = wmill.datatable('main', { role: 'operator' })
  */
 export function datatable(
   name: string = "main",
-  role?: string
+  opts?: DatatableOptions
 ): DatatableSqlTemplateFunction {
   let { name: n, schema } = parseName(name);
-  let provider = datatableProvider(n, schema, role);
+  let provider = datatableProvider(n, schema, opts?.role);
   let sqlFn = buildSqlTemplateFunction(provider) as DatatableSqlTemplateFunction;
   // `.query(sql, ...params)` is for SQL strings that already contain
   // positional placeholders ($1, $2, ...). We DON'T go through the template