# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Snowflake Table API
  version: 1.0.0
extends: openapi/snowflake-table-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 22
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables'].get
  update:
    x-apievangelist-phrasing:
      intent: List the tables in a schema
      effect: read
      questions:
      - Which tables exist in this Snowflake schema?
      - Can I see tables I dropped recently but that haven't been purged yet?
      - Is there a way to include each table's dependency information when listing them?
      instructions:
      - text: List every table in this schema.
      - text: List the tables in this schema, including dropped ones still recoverable ({history}).
        slots:
          history: query.history
      - text: Show all tables here with dependency details turned on ({deep}).
        slots:
          deep: query.deep
      - text: List the tables in schema {schema} of database {database}.
        slots:
          database: path.database
          schema: path.schema
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new table
      effect: write
      questions:
      - How do I create a new table with defined columns in a schema?
      - Can I set clustering keys and data retention when I first create a table?
      - What happens if I want change tracking turned on from the start of a new table?
      instructions:
      - text: Create a new table named {name} with columns {columns}.
        slots:
          name: requestBody.name
          columns: requestBody.columns
      - text: Create table {name} clustered by {cluster_by} and keep {data_retention_time_in_days} days of Time Travel.
        slots:
          name: requestBody.name
          cluster_by: requestBody.cluster_by
          data_retention_time_in_days: requestBody.data_retention_time_in_days
      - text: Create table {name} in database {database}, schema {schema}, with columns {columns}.
        slots:
          database: path.database
          schema: path.schema
          name: requestBody.name
          columns: requestBody.columns
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}:as_select'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a table from a query (legacy endpoint)
      effect: write
      questions:
      - Is there an older as_select endpoint that names the new table in the URL path?
      - What does the legacy underscore-style create-table-as-select call need from me?
      instructions:
      - text: Using the legacy as_select endpoint, create table {name} from the results of {query}.
        slots:
          name: requestBody.name
          query: query.query
      - text: Run the deprecated table-as-select call to materialize {query} into {name}.
        slots:
          query: query.query
          name: requestBody.name
      - text: Through the legacy as_select route on table path {table} in {database}.{schema}, save {query} as table {name}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
          name: requestBody.name
          query: query.query
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables:as-select'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a table from a SELECT query result
      effect: write
      questions:
      - Can I turn the output of a SELECT statement into a brand-new table?
      - How do I materialize query results as a table and pick its clustering keys?
      instructions:
      - text: Create a table called {name} populated from the query {query}.
        slots:
          name: requestBody.name
          query: query.query
      - text: Materialize the results of {query} into a new table {name}, clustered by {cluster_by}.
        slots:
          query: query.query
          name: requestBody.name
          cluster_by: requestBody.cluster_by
      - text: In {database}.{schema}, create table {name} from the rows returned by {query}.
        slots:
          database: path.database
          schema: path.schema
          name: requestBody.name
          query: query.query
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}:using_template'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a table from staged file templates (legacy)
      effect: write
      questions:
      - Is there an older using_template endpoint that takes the table name in the path?
      - What does the deprecated create-from-template call expect as its query?
      instructions:
      - text: Use the legacy using_template endpoint to create a table from the template query {query}.
        slots:
          query: query.query
      - text: Call the deprecated template-based table creation with {query} inferring columns from staged files.
        slots:
          query: query.query
      - text: Via the old using_template route, create table {table} in {database}.{schema} from template query {query}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
          query: query.query
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables:using-template'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a table from templates in staged files
      effect: write
      questions:
      - Can I create a table whose columns are inferred from files sitting in a stage?
      - How do I build a table definition from a template query over staged Parquet or CSV files?
      instructions:
      - text: Create table {name} using the column template returned by {query}.
        slots:
          name: requestBody.name
          query: query.query
      - text: Build a new table from my staged files' schema template with {query}.
        slots:
          query: query.query
      - text: In database {database}, schema {schema}, create table {name} whose columns come from template {query}.
        slots:
          database: path.database
          schema: path.schema
          name: requestBody.name
          query: query.query
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Describe a single table
      effect: read
      questions:
      - What columns, clustering and retention settings does this table have?
      - Can I pull the full describe output for one specific table?
      instructions:
      - text: Describe this table and show its columns and properties.
      - text: Fetch the definition of the table I named.
      - text: Describe table {table} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or alter a table with a full definition
      effect: write
      questions:
      - Can I alter an existing table by resubmitting its whole definition?
      - Why must I send every table property even when I'm only changing one?
      instructions:
      - text: Create or update table {name} so its columns match {columns}.
        slots:
          name: requestBody.name
          columns: requestBody.columns
      - text: Alter table {name} to set the comment {comment}, resending the full property set.
        slots:
          name: requestBody.name
          comment: requestBody.comment
      - text: Create or alter table {table} in {database}.{schema} to match the definition with columns {columns}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
          columns: requestBody.columns
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Drop a table
      effect: destructive
      questions:
      - How do I drop a table I no longer need?
      - Can a table be removed by name through the REST API?
      instructions:
      - text: Drop this table.
      - text: Delete the table I named from its schema.
      - text: Drop table {table} from schema {schema} in database {database}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}:clone'].post
  update:
    x-apievangelist-phrasing:
      intent: Clone a table, optionally at a point in time
      effect: write
      questions:
      - Can I make a zero-copy clone of a table into another schema?
      - Is it possible to clone a table as it looked at an earlier point in time?
      instructions:
      - text: Clone this table into a new table named {name}.
        slots:
          name: requestBody.name
      - text: Clone this table as {name} into database {targetDatabase} and schema {targetSchema}.
        slots:
          name: requestBody.name
          targetDatabase: query.targetDatabase
          targetSchema: query.targetSchema
      - text: Clone this table as {name} as of {point_of_time}.
        slots:
          name: requestBody.name
          point_of_time: requestBody.point_of_time
      - text: Clone table {table} in {database}.{schema} into a new table {name}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}:create_like'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an empty copy of a table (legacy)
      effect: write
      questions:
      - Is there a legacy create_like endpoint that takes the new table name as a query parameter?
      - What does the older underscore create-like call require?
      instructions:
      - text: Use the legacy create_like endpoint to make an empty table {newTableName} shaped like this one.
        slots:
          newTableName: query.newTableName
      - text: Call the deprecated create-like operation to produce {newTableName} with no rows.
        slots:
          newTableName: query.newTableName
      - text: With the legacy create_like route, make empty table {newTableName} shaped like {table} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
          newTableName: query.newTableName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}:create-like'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an empty table with the same structure
      effect: write
      questions:
      - Can I create a new empty table that copies another table's columns but none of its data?
      - What's the way to duplicate a table's structure without cloning its rows?
      instructions:
      - text: Create an empty table {name} with the same structure as this one.
        slots:
          name: requestBody.name
      - text: Copy this table's definition into a new, empty table called {name}.
        slots:
          name: requestBody.name
      - text: Make an empty table {name} with the structure of {table} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}:undrop'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a dropped table
      effect: write
      questions:
      - Can I bring back a table I accidentally dropped?
      - How do I recover a deleted table while it's still inside the retention window?
      instructions:
      - text: Undrop the table I deleted by mistake.
      - text: Restore this dropped table.
      - text: Undrop table {table} in schema {schema} of database {database}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}:suspend_recluster'].post
  update:
    x-apievangelist-phrasing:
      intent: Suspend automatic reclustering (legacy)
      effect: write
      questions:
      - Is there an older suspend_recluster endpoint with an underscore in the path?
      - Does the legacy call still pause reclustering on a table?
      instructions:
      - text: Use the legacy suspend_recluster endpoint to pause reclustering on this table.
      - text: Call the deprecated underscore route to stop this table from reclustering.
      - text: Via the legacy suspend_recluster route, halt reclustering of {table} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}:suspend-recluster'].post
  update:
    x-apievangelist-phrasing:
      intent: Suspend automatic reclustering on a table
      effect: write
      questions:
      - How can I stop automatic clustering from consuming credits on a table?
      - Can I pause reclustering on a single table temporarily?
      instructions:
      - text: Suspend automatic reclustering on this table.
      - text: Pause clustering maintenance for the table I named.
      - text: Suspend reclustering for table {table} in database {database}, schema {schema}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}:resume_recluster'].post
  update:
    x-apievangelist-phrasing:
      intent: Resume automatic reclustering (legacy)
      effect: write
      questions:
      - Is there an older resume_recluster endpoint that still restarts clustering?
      - What does the deprecated underscore resume-recluster route do?
      instructions:
      - text: Use the legacy resume_recluster endpoint to restart reclustering on this table.
      - text: Call the deprecated underscore route to turn clustering back on for this table.
      - text: Via the legacy resume_recluster route, restart reclustering of {table} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}:resume-recluster'].post
  update:
    x-apievangelist-phrasing:
      intent: Resume automatic reclustering on a table
      effect: write
      questions:
      - How do I turn automatic clustering back on after suspending it?
      - Can reclustering be restarted for just one table?
      instructions:
      - text: Resume automatic reclustering on this table.
      - text: Restart clustering maintenance for the table I suspended earlier.
      - text: Resume reclustering for table {table} in database {database}, schema {schema}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}:swapwith'].post
  update:
    x-apievangelist-phrasing:
      intent: Swap two tables (legacy endpoint)
      effect: write
      questions:
      - Is there an older swapwith endpoint that takes only the target table name?
      - What does the legacy table swap call need?
      instructions:
      - text: Use the legacy swapwith endpoint to swap this table with {targetTableName}.
        slots:
          targetTableName: query.targetTableName
      - text: Call the deprecated swap route to exchange this table and {targetTableName}.
        slots:
          targetTableName: query.targetTableName
      - text: Using the legacy swapwith route, swap {table} in {database}.{schema} with {targetTableName}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
          targetTableName: query.targetTableName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}:swap-with'].post
  update:
    x-apievangelist-phrasing:
      intent: Swap a table with another table
      effect: write
      questions:
      - Can I atomically swap a staging table into production?
      - Is it possible to swap with a table that lives in a different database or schema?
      instructions:
      - text: Swap this table with {targetName}.
        slots:
          targetName: query.targetName
      - text: Swap this table with {targetName} in database {targetDatabase}, schema {targetSchema}.
        slots:
          targetName: query.targetName
          targetDatabase: query.targetDatabase
          targetSchema: query.targetSchema
      - text: Swap table {table} in {database}.{schema} with table {targetName}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
          targetName: query.targetName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}:set-tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Set tags on a table
      effect: write
      questions:
      - How do I attach governance tags to a table?
      - Can I label a table with a cost-center or sensitivity tag?
      instructions:
      - text: Set tags on this table.
      - text: Apply my tag assignments to the table I named.
      - text: Set tags on table {table} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}:unset-tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove tags from a table
      effect: write
      questions:
      - Can I remove a tag that was assigned to a table?
      - What's the way to clear governance tags off a table?
      instructions:
      - text: Unset the tags on this table.
      - text: Remove the tag assignments from the table I named.
      - text: Unset tags on table {table} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tables/{name}:get-tags'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the tags assigned to a table
      effect: read
      questions:
      - Which tags are currently assigned to this table?
      - Does reading a table's tags need an active warehouse?
      instructions:
      - text: Show every tag assigned to this table.
      - text: List the tag assignments on the table I named.
      - text: Get the tags assigned to table {table} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          table: path.name
      method: generated
      generated: '2026-10-01'