> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pawsql.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> PawSQL 是一个产品：Cloud 是公网部署形态，Engine / Optimizer / Auditor / Advisor / Patroller 是同一产品的组件与交付形态，不是彼此独立的产品。 / PawSQL is a single product: Cloud is the public deployment form, while Engine / Optimizer / Auditor / Advisor / Patroller are components and delivery forms of the same product, not separate products.
> 术语以站内术语表为准：SQL 审核对应英文 SQL Review，查询重写对应 Query Rewrite，索引推荐对应 Index Recommendation；英文内容统一用 Review，不用 Audit。 / Use the site glossary for terminology: 审核 is SQL Review, 重写 is Query Rewrite, 索引推荐 is Index Recommendation; English content uses Review, never Audit.
> 引用能力范围或版本支持时以对应页面为准；标注 unknown、或 status 非 published 的内容表示尚未经产品核实，不应作为事实引用。 / Cite capability scope and version support from the corresponding page; content marked unknown, or with a status other than published, is not yet product-verified and must not be cited as fact.

# 创建优化任务（异步）

> 创建 SQL 优化任务后立即返回，通过 `/getAnalysisSummary` 轮询优化结果。
适用于长查询或需要避免 HTTP 超时的场景。




## OpenAPI

````yaml /openapi/pawsql-optimization.yaml post /createAnalysisAsync
openapi: 3.0.3
info:
  title: PawSQL 优化服务
  description: |
    PawSQL SQL 优化服务对外接口。

    PawSQL 优化引擎是为开发者和 DBA 开发的查询优化引擎，集成了数据库行业的查询优化最佳实践，
    提供强大的 SQL 审核和重写优化功能，并集成 Paw Index Advisor 索引推荐引擎为慢查询提供基于成本的索引推荐。

    ## 认证方式

    大部分接口需要通过 `userKey`（激活码）进行身份认证。
    `userKey` 可通过 `/getUserKey` 接口（邮箱密码登录）获取。

    ## 接口调用流程

    1. 调用 `/getUserKey` 获取 userKey
    2. 调用 `/createWorkspace` 创建工作空间（或直接在 `/createAnalysis` 中传入 DDL）
    3. 调用 `/createAnalysis` 或 `/createAnalysisAsync` 创建优化任务
    4. 调用 `/getAnalysisSummary` 获取优化汇总
    5. 调用 `/getStatementDetails` 获取单条 SQL 优化详情
  version: 1.0.0
  contact:
    name: PawSQL Team
    url: https://pawsql.com
  license:
    name: PawSQL
    url: https://pawsql.com
servers:
  - url: /api/v1
    description: PawSQL Server
security:
  - userKey: []
tags:
  - name: 身份认证
    description: 身份认证接口
  - name: 工作空间
    description: 工作空间管理接口
  - name: SQL优化
    description: SQL 优化任务接口
paths:
  /createAnalysisAsync:
    post:
      tags:
        - 优化任务
      summary: 创建优化任务（异步）
      description: |
        创建 SQL 优化任务后立即返回，通过 `/getAnalysisSummary` 轮询优化结果。
        适用于长查询或需要避免 HTTP 超时的场景。
      operationId: createAnalysisAsync
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiAnalysisCreate'
            examples:
              example:
                value:
                  userKey: CB698418-88B25371-67F15F01-XXXXXXXX
                  workspace: '1730508173442965506'
                  workload: select * from organization where adm_id = 100;
                  queryMode: plain_sql
      responses:
        '200':
          description: 异步优化任务创建结果
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResult'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/AnalysisCreateResponse'
components:
  schemas:
    ApiAnalysisCreate:
      type: object
      description: 创建优化任务请求
      required:
        - userKey
        - workspace
        - workload
        - queryMode
      properties:
        userKey:
          type: string
          description: 激活码
          example: CB698418-88B25371-67F15F01-XXXXXXXX
        workspace:
          type: string
          description: 工作空间 ID 或 DDL 文本（传入 DDL 时自动创建离线工作空间）
        dbType:
          type: string
          description: |
            数据库类型（displayCode），当 workspace 为 DDL 时必填，默认 mysql。
            支持的 dbType 值见 /createWorkspace 接口的 dbType 表格。
        workload:
          type: string
          description: 待优化的 SQL 文本
        queryMode:
          type: string
          description: 'SQL 类型: plain_sql / mysql_query_log / postgresql_query_log'
          enum:
            - plain_sql
            - mysql_query_log
            - postgresql_query_log
          example: plain_sql
        validateFlag:
          type: boolean
          description: 是否执行 validate 校验（仅在线工作空间生效），默认 false
          default: false
        singleQueryFlag:
          type: boolean
          description: 是否校验仅单条 SQL
        analysisName:
          type: string
          description: 优化任务名称，不填则自动生成
        analyzeFlag:
          type: boolean
          description: 是否执行分析
        closeRewrite:
          type: boolean
          description: 是否关闭查询重写
        deduplicateFlag:
          type: boolean
          description: 是否去重索引
        updateStatsBeforeValidationFlag:
          type: boolean
          description: validate 前是否更新统计信息
        indexOnly:
          type: boolean
          description: 是否仅推荐索引（不重写）
        maxMembers:
          type: integer
          description: 复合索引最大列数
        maxMembersForIndexOnly:
          type: integer
          description: index-only 模式复合索引最大列数
        maxPerTable:
          type: integer
          description: 每张表最大推荐索引数
        maxSpace:
          type: integer
          description: 最大索引空间倍数
        rules:
          type: array
          description: 自定义规则列表，不填则使用默认审计规则
          items:
            $ref: '#/components/schemas/RuleBasicRead'
    ApiResult:
      type: object
      description: 统一响应体
      properties:
        code:
          type: integer
          description: 状态码，200 表示成功
          example: 200
        message:
          type: string
          description: 描述信息
          example: Success
        data:
          description: 响应数据
    AnalysisCreateResponse:
      type: object
      description: 创建优化任务响应
      properties:
        analysisId:
          type: string
          description: 优化任务 ID
          example: '1730505660018876418'
        status:
          type: string
          description: '优化状态: success / success0 / success1 / failed'
          example: success1
    RuleBasicRead:
      type: object
      description: 规则定义
      properties:
        ruleCode:
          type: string
          description: 规则编码
        rewrite:
          type: boolean
          description: 是否重写规则
        threshold:
          type: string
          description: 规则阈值
  securitySchemes:
    userKey:
      type: apiKey
      in: header
      name: userKey
      description: 激活码，通过 /getUserKey 接口获取

````