NCQL 教程

一、功能介绍

1、功能简介

NCQL是一款用于分析模型数据，分析模型是否满足某种特征的查询语言。它采用和参数化编辑器相似的公式语法，任何熟悉参数化建模的用户，都可以轻松上手使用NCQL。NCQL不仅可以识别模型有哪些特征，还能将相关联的数据记录下来，以方便地定位模型及其有问题的部分。

一段 NCQL 脚本，在本质上，是一个布尔（Bool）表达式，它接收一个模型的数据，判断模型是否满足某类特征。如果模型满足某类特征，则将它记录下来。

• NCQL 集成开发环境教程：点击查看

2、什么是NCQL？

1）简单的NCQL，如下图：

prodCatId == 785 AND （#D < 18 OR #D > 25） 

这条例子为我们展示了，NCQL可以使用与建模公式非常相似的表达式语法，来实现模型特征的分析。

2）复杂的NCQL，如下图：

// 寻找部件尺寸默认状态下超限的模型
findAnyOf subModels {
    findAnyOf parameters {         
        allTrue {
            name == "W" || name == "D" || name == "H" 
			// parameter 的方法，用于判断
            overLimited() 
        } -> mark "尺寸超限"
    }
}

二、面向用户

全体参数化编辑器建模的用户

三、操作步骤

1、数据类型

1）基本类型

对于参数的值，NCQL 提供和建模相同的数据类型。其中常用的有以下几种：

2）复杂类型

如果只有基本数据类型就好了，但可惜，真实的世界并不是只有像原子这样的微观粒子，而是由不同种类的微观粒子组合成新的个体，再不断向上组合的。比如我们人类是由不同种类的细胞组成的，而细胞又是由不同的分子组成的，分子又是由不同的原子组成的。

和真实的世界类似，模型的结构也是复杂的，由多个部分组成。一个父模型大致可以看作是由一组变量、一组子模型、一组属性组成的，而一个子模型，又是由一组变量、一组属性组成的。NCQL 聚焦于参数化模型编辑器中能看到的模型信息，因此子模型的子模型，不会在这里出现。

完整的数据结构文档，可以参考在线代码编辑器底部栏。

3）理解参数的表达式、当前值、计算值

在模型数据结构文档中，当你阅读到参数（Parameter）的数据结构时，可能会感到疑惑，总共有三个字段：value、parsedValue、expression用于描述参数的值。这是因为一个参数化模型，在不同的使用场景，有不同的数据表现。

后台建模时，建模师会编写表达式（expression），定义参数之间的计算逻辑和约束关系。

而到了设计工具中，模型会被“实例化”，模型上的表达式将会被计算为一个有类型信息的计算值（parsedValue）。

同时，这个计算值会被转化为字符串，作为参数的当前值（value）。

• 一个示例如下图所示：在建模中，参数W和D都是公式类型，建模师编写的表达式分别为"300 + 400.5" 和 "#W + 1"，而模型实例化后，这两个表达式分别被计算为两个 float 类型的值： 700.5 和 701.5。这两个值被放置到 parsedValue 字段。这两个值被转化为 "700.5" 和 "701.5" ，放置到 value 字段中。

• 以 W 为例，将这些数据组合到一个 Parameter 中，组合后的数据如下（其他字段省略）：

{
  "name": "W",
  "type": "float",
  "expression": "300 + 400.5",
  "parsedValue": 700.5,
  "value": "700.5"
}

4）编写安全的 NCQL

模型数据中，大部分可以直接访问到的字段，类型都在文档中有明确的声明。但唯独参数的 parsedValue 是什么类型，我们是无法提前分析得知的。

在 name.contains('万能柜') 这条表达式中，我们通过文档得知模型的 name 字段，类型是字符串，因此我们可以安全地调用 contains 方法，不用担心是否写错。

虽然参数的计算值是有可能是任意类型，但是有计算值的地方，一般都有一个 type 字段来表示这个 parsedValue 的类型，你可以通过读取 type字段来获取参数类型。

在以下的案例中，展示了先获取参数的类型，再判断参数的计算值是否大于1000。（此案例中表达式 "." 的语法，在下文 表达式 章节会讲解）。

// 假设有一个叫做 A 的变量，表示某个 FParentParameter
#A.type == "float" && #A.parsedValue > 1000

2、变量

1）NCQL 的和模型的建模表达式非常像，在建模中，你可以通过 '#' 读取各种数据，如 "#W" 代表读取参数W的值。在NCQL中，我们同样支持这种写法，并把这些可以使用 '#' 读取的数据，称作变量。变量有变量名和变量值。为了方便使用，系统会预置一些变量:

• 变量名：model，变量值：当前查询的主体，即当前查询的模型。
• 当前模型的所有参数，都会作为一个变量，预置到查询环境中。
  • 对于每个参数来说，变量名：参数名，变量值：参数的计算值（parsedValue）。

2）假设有以下模型，有 W、D、H、materialBrandGoodId 四个参数，则系统内置的变量有：

• model，变量值：当前查询的模型 FParentModel；
• W，变量值：当前查询的模型参数 W 的计算值 parsedValue；
• D，变量值：当前查询的模型参数 D 的计算值；
• H，变量值：当前查询的模型参数 H 的计算值；
• materialBrandGoodId，变量值：当前查询的模型参数 materialBrandGoodId 的计算值。

需要注意的是，由于parsedValue的类型不确定性，除非你非常确定某个参数的类型（如W、D、H 肯定是float类型），请谨慎直接使用这些变量。

3、注释

NCQL 支持注释，注释就是对 NCQL 的解释和说明，其目的是让你能够更加轻松地阅读、编写NCQL。注释不会被 NCQL执行器识别，不会影响到 NCQL 执行器的工作流程。

• 语法定义：以双斜杠 “//”开头，到一行的结尾，如下图：

// 这一行是注释，不会被NCQL执行
#W > 6000 // 行末的这部分也是注释，同样不会被执行

4、基于建模公式扩展的表达式语法

1）NCQL 的表达式，扩展自参数化建模公式语法。如：

• #W + #D < 1000，是一个布尔类型的表达式，含义为判断模型参数 W 和 D 的和是否小于1000，计算结果为 true 或 false；
• #W + #D + 1.0 是一个浮点数类型的表达式，含义为计算模型参数 W 和 D 的和，并加上 1.0，计算结果为浮点数。

2）与参数化建模的公式相同的是，NCQL 使用#变量名 来引用当前上下文中可用的变量，用 #函数名(参数1, 参数2, ...其余参数) 来调用函数。

3）与参数化建模不同的是，NCQL 的表达式进行了一些扩展，允许使用以下更高级的特性:

• 可以使用 字段名 来获取某个变量的的字段值。如：
  • #model.prodCatId == 735 来判断 model 变量的 prodCatId 是否为 735
  • #model.name == '万能柜'来判断 model 变量的 name 是否为 '万能柜'
• 在已知类型的变量上，可以调用变量支持的方法。如：
  • #model.getParamValue('W') ，表示调用 model 变量的 getParamValue 方法，并传入参数 'W'
  • #str.contains('a') 表示调用 str 变量的 contains 方法，并传入参数 'a'。

4）具体哪些类型，有哪些方法可用，见各个数据类型的文档。

#model.prodCatId == 999 AND (#W > 1000 OR #D > 1000 OR #H > 1000)

#model.paramType("WLH") == "int"

#model.name.contains("下柜") OR #model.name == "万能柜"

5、查询主体

1）上述的例子中，读取模型上的字段，或调用模型的方法，都需要指定前缀 “#model.xxx" 。有没有一种办法，能简化这些表达式呢？ 答案是 查询主体。在NCQL中，每一行表达式都会作用一个查询主体，查询主体默认为 model。

2）你可以直接省略前缀，来读取当前查询主体上的字段。下图展示了一个示例的模型数据，以及三组含义相同的表达式：

3）虽然使用基于查询主体的省略表达式，可以让NCQL变得更加简洁易写，但需要注意的是，查询主体增加了理解成本，如表达式 “name” 是读取当前查询主体的name字段，而表达式 “#name” 是读取名为name的变量。并且查询主体可能会发生切换（见下文的”子查询块“），因此在使用时，需要更加小心。

6、查询块

1）一般而言，一条查询语句是完全不够分析模型的。我们需要将多条查询语句以灵活的方式进行组合。NCQL 中，查询块（queryBlock）就是用来实现查询语句的组合的。同时，过长的表达式难以阅读、编写与理解，使用查询块，可以优化查询语句的结构，使其更加清晰。

2）查询块本身返回一个bool值，它的语法如下，以匹配方式开头，以 { 和 } 包裹。

匹配方式 {
    查询语句1
    查询语句2
    ...
    查询块1
    查询块2
    ...
    子查询块1
    子查询块2
    ...
}

3）匹配模式包含以下三种：

allTrue：当查询块中的所有查询，都为true时，查询块为true，否则为false

anyTrue：当查询块中的任意一个查询为true时，查询块为true，否则为false

noneTrue：当查询块中的所有查询都为false时，查询块为true，否则为false

4）查询块内部，可以由多种不同的查询自由组合而成：

• 查询语句：布尔类型的表达式，不能换行。
• 查询块：递归的查询方式，以匹配模式开头，以 { 和 } 包裹。即查询块内部，还可以继续嵌套查询块
• 子查询块：见 子查询块 章节。

5）假设有如下复杂的表达式：

// 假设当前查询主体为某个参数
(paramTypeId == 1 && parsedValue < min && parsedValue > max)
     // 注意，这里为阅读方便，在 OR 之前使用了换行
     // 你在实际编写脚本的时候不能有这个换行
     OR paramTypeId == 2 && !optionValues.contains(value);

可以使用查询块来优化，使其更加清晰：将表达式从 || 进行拆分，最后使用 anyTrue 来表示或的关系。

// 假设当前查询主体为某个参数 
anyTrue {
    // 当参数的值类型为区间的时候，判断参数的值是否在区间内
    paramTypeId == 1 && parsedValue < min && parsedValue > max
    // 当参数的值类型为可选的时候，判断参数的值是否在选项列表中
    paramTypeId == 2 && !optionValues.contains(value)
}

进一步优化，将内部的两条查询语句，可以从 && 进行拆分，使用 allTrue 来表示与的关系。

anyTrue {
     allTrue {
        paramTypeId == 1 // 1为区间
        parsedValue < min && parsedValue > max
    }
    allTrue {
        paramTypeId == 2 // 2为可选
        !optionValues.contains(value)
    }
}

如果只是优化复杂的查询语句，那查询块的威力还不足以体现。真正需要它的地方，是下一节介绍的 子查询块 。

7、子查询块

子查询块同样返回一个布尔值，允许在查询块中深入模型结构，从而实现较为复杂的查询逻辑。子查询块大多数情况下，用于检查List字段，如模型的参数列表、子模型列表。

子查询块同样可以看成一条流水线，NCQL会尝试把List字段的每个元素，使用子查询块内部的判断条件进行检查。最终通过 查询方式，来确定最终返回的布尔值是什么。

1）子查询块 语法定义

子查询块的语法如下，以 查询方式 开头，以 { 和 } 包裹。包括可选的数据转换、可选的查询对象命名功能。

查询方式 要查询的字段 (as 查询对象命名)? {
    查询块
}

2）子查询查询方式

其中最核心的部分，即为查询方式。查询方式包含以下四种：

• findAnyOf：用于查询对应多个值的字段，如参数列表。当列表中任意一个值满足查询条件时，查询块为true。
• findAllOf：用于查询对应多个值的字段，如参数列表。当列表中所有值都满足查询条件时，查询块为Ttrue。
• findNoneOf：用于查询对应多个值的字段，如参数列表。当列表中所有值都不满足查询条件时，查询块为true。
• find：用于查询对应单个值的字段，如模型商品ID。当查询条件为true时，查询块为true。

这些查询方式的使用，如下图所示：

3）子查询切换查询主体

子查询的设计用意在于深入模型的结构，因此它能够自动切换当前查询的主体。如以下例子所示：

• 示例1：查询主体切换到某个参数

allTrue {
    prodCatId == 123 // 当前查询主体，还是model，因此 prodCatId 字段是模型的真分类

    findAnyOf parameters {
        // 在 findAnyOf 触发的子查询块中，当前查询的主体是每一个参数
         allTrue {
            // 此时，name字段表示参数的name字段，即参数名
            name == "W" || name == "D" || name == "H"
            paramTypeId == 5
        }
    }
}

• 示例2：查询主体切换到某个子模型

如以下模型结构：

当查询语句如下时：

allTrue {
     // 当前查询的主体是顶层柜体，name字段的值为 "柜体"
    name == "柜体"

    findAnyOf subModels {
        // 在 findAnyOf 触发的子查询块中，当前查询的主体是每一个子模型
        // 因此，当判断到左门板时，当前查询的主体是左门板，name字段的值为 "左门板"
        // 当判断到右门板时，当前查询的主体是右门板，name字段的值为 "右门板"
        name == "左门板"
    }
}

findAnyOf subModels {
    name == #model.name
}

findAllOf subModels {
    suppress == true
}

findAnyOf subModels {
    allTrue {
        name == "背板"
        findAnyOf parameters {
            name == "WLH"
        }
   }
}

findAnyOf subModes {
    ignore == true
}

4）子查询查询对象命名

子查询在查询的过程中，还可以为当前正在查询的变量进行命名。在子查询块声明语句中，最后面加一个 as 变量名。如以下例子中，当前正在查询的参数，被命名为了p。因此 #p.paramTypeId == 5 和 paramTypeId == 5 是完全等价的两个表达式。

findAnyOf parameters as p {
    #p.paramTypeId == 5 OR paramTypeId == 5
}

它的意义在于，当你需要嵌套子查询时，由于查询主体发生了切换，在内层的子查询，是无法直接读取外层子查询主体的字段的。在这种情况下，我们可以为外层子查询的主体进行命名，这样我们可以实现更复杂的查询。

findAnyOf subModels as subModel {
    allTrue {
               // 此处，name表示subModel的name字段，和 #subModel.name 等价
                   name == "下柜" 
        
                    findAnyOf parameters {
                        // 这里name字段，是读取的当前查询主体（parameter）的name
                        // 想读取外层子查询主体的name，需要使用 #subModel.name
                        name == #subModel.name
                    }
        }
}

需要注意的是，子查询块声明的变量，只在子查询块中有效。在此子查询块外的表达式，将无法使用这个变量。具体见章节变量作用域

findAnyOf subModels as m {     
    allTrue {
        refName.isNotBlank()   
        anyTrue {
			position.xExpression.contains("@self" + #m.refName)
		 	position.yExpression.contains("@self" + #m.refName)
		 	position.zExpression.contains("@self" + #m.refName)
		}
    }
}

8、变量声明

1）变量声明属于高阶特性，大多数场景不需要使用变量声明。

2）NCQL 允许在查询脚本中的大部分位置定义变量，变量可以在表达式中使用。当变量声明语句出现在查询块中时，它只是简单地向环境中设置变量，不会影响当前查询块的判断。

3）定义变量的语法是：

let 变量名 = 表达式

4）如：

let a = #model.getParameter('W').min;
let b = #model.getParameter('D').max;
let c = #W + #D;
let names = #listOf('W', 'D', 'H');

9、变量作用域

1）NCQL 中声明的变量，作用域是当前查询块。如果在子查询块中声明的变量，则只在当前子查询块中生效。

2）在以下示例中，我们展示了 NCQL 中变量的作用域规则。变量 a 在外层查询块中被声明并赋值为 1，而变量 b 则在内层的 findAnyOf 查询块中被声明并赋值为 2。

allTrue {
    let a = 1; // 变量 a 在此作用域内可用
    findAnyOf parameters {
        let b = 2; // 变量 b 仅在此子查询块内可用         
        allTrue {
            #a == 1 // 访问外层的变量 a，值为 1
            #b == 2 // 访问内层的变量 b，值为 2
        }
    }
    // 这里无法访问到 b 变量，因为 b 的作用域仅限于 findAnyOf 子查询块
    #a == 1; // 仍然可以访问变量 a
}

3）在这个示例中，#a 可以在外层查询块中被访问，而 b 只能在其声明的 findAnyOf 子查询块中使用。这说明了 NCQL 中变量的作用域是局部的，子查询块中的变量不会影响外层查询块的变量。

10、查询后操作

1）当你在NCQL中分析得到模型有某种特征时，你可能会希望记录一些信息。这时你可以使用mark语法来记录这些信息，这些信息将会出现在批量分析结果的 Excel 表中。

2）查询后操作的语法定义如下：它可以跟在布尔表达式、查询块、子查询后面。当这些查询块计算结果为 true 时，查询后操作中的指令将会被执行。

布尔表达式 -> mark 字符串或 Marker 函数
查询块 -> mark 字符串或 Marker 函数
子查询 -> mark 字符串或 Marker 函数 

3）看下面的这段脚本。比如，当你发现某个部件的某个参数超出了限制，你希望记录下来这个参数的名称。这时，你可以使用 “查询后操作” 语法的 mark。如以下脚本所示，这里我们使用字符串拼接操作，记录了超限的部件名和参数名。

如果部件的尺寸确实超限了，那么 allTrue 后的 mark指令将会被执行。 分析结果的excel表中，会出现如“部件 【左侧板】的参数【宽度】超限”的文案。

// 寻找部件尺寸默认状态下超限的模型
findAnyOf subModels as s {
    findAnyOf parameters as p {
        allTrue {
            name == "W" || name == "D" || name == "H"
            overLimited()
        } -> mark "部件【"+#s.name+"】的参数【"+ #p.displayName+"】超限"
    }
}

4）在 → mark 后，你可以简单地写字符串，也可以根据信息的严重程度，来使用不同的mark函数。我们提供了三种严重程度的mark：

• 信息（即 info）：这代表简单地记录一些信息。你可以使用 mark -> 字符串 的语法来记录info。
• 警告（即 warn）：这代表记录的信息是不太严重，但需要关注的问题，你可以使用 mark -> #warn(字符串) 的函数来记录警告。
• 错误（即 error）：这代表记录的信息是严重的错误，必须尽快修复。你可以使用 mark -> #warn(字符串) 的函数来记录错误。

5）如下例子所示，如果部件商品被删除了，在设计工具中无法正常使用。所以这是一种严重的错误，使用 #error 函数来记录。

findAnyOf subModels {
    #relatedProduct(brandGoodId).deleted -> mark #error("部件被删除")
}