< 上一课 | 下一课 >

定义搜索条件

您可以使用查询过滤器定义查询的搜索条件,这些过滤器基于对用户数据库中每条记录的字段的比较。该查询将在 ResultSet 对象中返回数据库中与搜索条件匹配的所有记录。

每次比较都是 QueryFilterNode 对象的一个实例,由过滤器实施。过滤器允许您将一个字段与单一值或某个范围内的多个值进行比较。为过滤器选择的运算符确定要执行的比较类型。 要获取有效运算符的列表,请参阅 CompOp 常量枚举类型。要创建过滤器的分层树,请使用布尔运算符将它们连接在一起,并可以将某些过滤器嵌套在另一些过滤器中。 每个过滤器包含单一条件,或使用 AND 或 OR 运算符连接在一起的一组条件。在构建自己的过滤器时,您可以嵌套多组更为复杂的过滤器,以创建一组复杂的搜索逻辑。

以下是设计查询时常用的一些对象以及处理查询的方法:
  • QueryDef 对象:
    • BuildQuery(记录类型)- 针对指定记录类型的新查询
    • BuildField(指定要显示的字段)。
    • BuildFilterOperator 方法需要枚举常量 - BoolOpConstant(And/Or)。
  • Session 对象:
    • BuildResultSet 方法(从查询检索到的数据的占位符)。
  • ResultSet 对象:
    • BuildResultSet 方法(从查询检索到的数据的占位符)。
    • Execute 方法(运行查询并检索产生的数据)。
    • MoveNext 方法(将游标移至数据集中的下一条记录)。
    • GetColumnLabel 方法(已获取的字段标签文本)- 例如,“Headline”、“id”以及“State”
    • GetColumnValue 方法(获取特定于字段的数据)- 例如,“SAMPL00000014”、“This is my headline”以及“Submitted”
  • QueryFilterNode 对象:
    • BuildFilter(过滤器参数)需要 CompOpConstant 枚举常量(如 EQ、NEQ、GT、GTE、LT 以及 LTE)形式的比较运算符(如 In、Equal、Less Than、Greater Than 以及 Is Null)和要比较的值(如 State EQ Submitted),以及一个 Perl 字符串数组,该数组包含要与指定字段中的值进行比较的值。
    • BuildFilterOperator 方法需要枚举常量 - BoolOpConstant

设计查询时,您可以使用以上列出的方法,如下所示:

  1. 使用 BuildQueryDef 方法来构建 QueryDef 对象:$QueryDef = $Session->BuildQueryDef(entity-def-name)
  2. 使用 BuildField 方法添加要选择的字段:$QueryDef->BuildField(field-name)
  3. 将查询过滤器构建为 And/Or 树。And/Or 节点是 QueryFilterNode 对象。使用 BuildFilterOperator 方法构造树的顶级节点:$QueryFilterNode = $QueryDef->BuildFilterOperator(bool)
  4. 使用以下方法,将 And/Or 比较节点添加为 QueryFilterNode 对象的子代:QueryFilterNode = $QueryFilterNode->BuildFilter(field,CompOp,value)$QueryFilterNode->BuildFilterOperator(bool) 例如,要针对表达式 priority = 1 and (component = gui or owner = joe) 进行过滤:
    $and_node = $querydef->BuildFilterOperator(And); 
    $and_node->BuildFilter("priority",eq,1); 
    $or_node = $and_node->BuildFilterOperator(Or); 
    # The third argument of the BuildFilter method must be a reference to an array:
    # Here we first build the array @comp, then pass 
    # the reference \@comp into the BuildFilter method.
    @comp = ("gui");
    $or_node->BuildFilter("component", $CQPerlExt::CQ_COMP_OP_EQ, \@comp); 
    @name = ("Joe"); 
    $or_node->BuildFilter("owner", $CQPerlExt::CQ_COMP_OP_EQ, \@name);
    
    # Another way to pass the array reference for simple values is using anonymous arrays. For example:
    $or_node->BuildFilter("owner", $CQPerlExt::CQ_COMP_OP_EQ, ["Joe"]);

示例

以下示例包含一些查询过滤器,扩展了前一主题中的示例:

use CQPerlExt; 
#Start a Rational ClearQuest session 
$SessionObj = CQSession::Build(); 

$dbsetname = "CQMS.SAMPL.HOME"; 

#Refresh list of accessible databases 
$databases = $SessionObj->GetAccessibleDatabases("MASTR", "", $dbsetname); 

#Log into a database 
$SessionObj->UserLogon("admin","","SAMPL",$dbsetname); 

#Create a Query 
$querydef = $SessionObj->BuildQuery("defect"); 
$querydef->BuildField("id"); 
$querydef->BuildField("headline"); 
$querydef->BuildField("owner.login_name"); 
$querydef->BuildField("submit_date"); 

#Create the queryfilternode object: 
# where (state is not Closed AND (id = 1 OR id = 2)) 
$where = $querydef->BuildFilterOperator($CQPerlExt::CQ_BOOL_OP_AND); 

# All filter values passed in as a reference to an array.
@states = ("closed"); 
$where->BuildFilter("state", $CQPerlExt::CQ_COMP_OP_NEQ, \@states); 
# Another way to pass the array reference for simple values is using an anonymous array, like this:
# $where->BuildFilter("state", $CQPerlExt::CQ_COMP_OP_EQ, ["closed"]);

$subor = $where->BuildFilterOperator($CQPerlExt::CQ_BOOL_OP_OR); 

@id1 = ("SAMPL00000001"); 
$subor->BuildFilter("id", $CQPerlExt::CQ_COMP_OP_EQ, \@id1); 

@id2 = ("SAMPL00000002"); 
$subor->BuildFilter("id", $CQPerlExt::CQ_COMP_OP_EQ, \@id2); 

$resultset = $SessionObj->BuildResultSet($querydef); 

$ct = $resultset->ExecuteAndCountRecords(); 
for ($i = 0; $i < $ct; $i++) { 
   $resultset->MoveNext(); 
   print $resultset->GetColumnValue(1); 
   print " "; 
   print $resultset->GetColumnValue(2); 
   print " "; 
   print $resultset->GetColumnValue(3); 
   print " "; 
   print $resultset->GetColumnValue(4); 
   print "\n"; 
   } 
CQSession::Unbuild($SessionObj);
< 上一课 | 下一课 >

反馈