Pegasus Enhancement Proposal (PEP)
PEP #: 138
Title: CQL Stage 1
Version: 1.11
Created:
Authors: Oliver Benke, Chuck
Carmack
Status:
Approved,
Ballot 75, Nov 2004
Version
History:
|
Version |
Date |
Author |
Change Description |
|
1.0 |
|
Oliver Benke |
Initial Submission |
|
1.1 |
|
Oliver Benke |
Removed execQuery support Restricted to CMPI providers Restricted to feature level 1 with more precise definition in
DMTF Different behavior for virtual properties Changed from OBJECTNAME to OBJECTPATH some minor changes Incorporated comments from Pegasus developers |
|
1.2 |
|
Oliver Benke |
Refer to POSIX REGEX Include Pegasus C++ API Added some comments Added TODO section |
|
1.3 |
|
Oliver Benke |
Removed virtual properties/ path functions (A)BNF now in the appendix Added details on CIM_QueryCapabilities Removed restriction on CMPI providers Added section on handling of not supported CQL query strings |
|
1.4 |
|
Oliver Benke |
- Updated discussion section - Removed error in ABNF from CQL query spec 0.11 which prevents
arithmetic on datetime values; fixes in ABNF are suggested by George Ericsson
and they are marked with OB> - CIM_ERR_INVALID_QUERY as possible error code, instead of
CIM_ERR_NOT_SUPPORTED - don't refer to GNU software, like OpenLDAP did, for legal
reasons |
|
1.5 |
|
Chuck Carmack |
-
Updated the section on IndicationService and QueryExpression class |
|
1.6 |
25 May 2004 |
Oliver Benke |
Updates
based on DMTF CIM Query Spec version 0.12 ( |
|
1.7 |
27 May 2004 |
Oliver Benke |
Updates
based on DMTF CIM Query Spec version 0.13 ( -
Basic
Like Regular Expressions are now easy to implement -
Basic
array support (in specific-property-name clause) is part of basic query feature,
so should be part of this PEP as well |
|
1.8 |
|
Oliver Benke |
added
CR1386 various
fixes |
|
1.9 |
|
Oliver Benke |
Various
updates |
|
1.10 |
|
Oliver Benke |
Changed
to concept PEP Worked
on LIKE |
|
1.11 |
|
Oliver Benke |
Updates
based on input by Carol Ann Krug Graves and Chuck Carmack (see discussion
archive) |
Abstract: This PEP proposes the implementation of a subset of CQL for indication filter strings (event based monitoring).
This PEP is based on DMTF CIM Query Language Specification
(DSP0202, aka CQL spec). The latest version of the CQL spec available at the
time this was written was Version 1.0.0a from
Please note that ExecQuery or ExecuteQuery support is not part of this PEP.
For now, the CQL implementation needs to be experimental, with PEGASUS_USE_EXPERIMENTAL applied.
This PEP is not focused on the implementation details but on
the requirements to be fulfilled. More implementation details can be found in
PEP #193.
This PEP is meant to get Pegasus CQL implementation started (together with subsequent PEP #193) and to outline the requirements and what’s the content of CQL Stage 1 implementation in Pegasus.
CQL as implemented in stage 1 in Pegasus (PEP #193) can be used by indication providers in order to parse the CQL indication filter queries much the same way they can use WQL today. However, in the long term, the CQL parser implementation should be useable to also support executeQuery interface and other applications, like filtered associations.
The assumption is that CQL and WQL will co-exist for some
while. However, WQL was never really standardized, and existing implementations
are not interoperable.
There is a certain risk in that the CQL spec is not finalized right now.
The following query features have to be implemented with this PEP:
For embedded properties, please refer to PEP 158 and subsequent PEPs, as embedded object support is currently missing in Pegasus.
In the ABNF in DSP0202, everything which belongs to Basic Query is in bold font.
Please note that query feature “Arithmetic Expression” used to be part of “Basic Query”, but this is no longer the case. PEP #193 won’t implement support for arithmetic expressions.
Reason for choosing query features Basic Query and Embedded Properties: as a first useful and most easy to support use case for CQL, we have chosen to support indication filtering support. Basic Query is considered to be the minimum needed for most CQL applications, and it has actually been defined with indication filtering support in mind. In order to support life-cycle indications, embedded properties are needed as well.
PEP #193 - CQL stage 1
functional design
PEP #158 - the stage 1 embedded objects support in the Lifecycle
Indications concept PEP; the related function PEP is #194.
PEP #172 – base embedded object encoding/ decoding support
PEP #194 - functional PEP
for stage 1 embedded objects support for the Lifecycle Indications, based on
PEP #158.
PEP #192 – CIMDateTime functional enhancements
Implementation details are now described in PEP #193.
Both the CMPI
provider interface as well as the Pegasus C++ interface have to be supported.
Details on the SDK level can be found in the PEP #193 on CQL stage 1 functional
design.
Although PEP #119 is focused on ExecQuery operations and this PEP (#138) does not include CQL support for ExecuteQuery (because of the current state of discussion with regard to CIM_QueryResult), the query language independent framework described in PEP #119 should be extended for CQL.
The CQL parser MUST be able to accept input in utf-8 format.
If the query contains any statement
which cannot be parsed, which is not part of the implemented subset of CQL, a
parse error must be generated according to DSP0202 (CIM Query Language
Specification).
With DMTF
Interop-00206, a CIM_QueryCapabilities class is added to the CIM Schema 2.9
preliminary in order to enable applications to find out which features of the
CQL language are implemented.
The change
request looks like this:
// ==================================================================
// QueryCapabilities
// ==================================================================
[Experimental, Version ("2.8.1000"), Description (
"This class
defines the query capabilities of a CIM_ObjectManager "
"and/or CIM_Provider, as associated
via ElementCapabilities.") ]
class CIM_QueryCapabilities : CIM_Capabilities {
[Description (
"Enumeration of CQL
features supported by an Object "
"Manager or
Provider associated via ElementCapabilities. "),
ValueMap {"2", "3",
"4", "5", "6", "7", "8",
"9", "10", "11",
"12", "13", “14”, "..", "0x8000.."},
Values {"Basic Query",
"Simple Join", "Complex Join",
"Subquery",
"Result Set Operations", "Extended Select List",
"Embedded Properties",
"Aggregations", "Regular Expression Like",
"Array Range",
"Satisfies Array", "Foreign Namespace Support",
“Arithmetic Expression”,
"DMTF Reserved", "Vendor Reserved"}
]
uint16 CQLFeatures[];
};
A provider to
create a CIM_QueryCapabilities instance like this has to be implemented:
instance of CIM_QueryCapabilities {
Caption = "CQL Parser Capabilities";
Description
= "This instance contains information on which CQL features are
implemented by the CQL implementation in this version of OpenPegasus.";
InstanceID =
"OpenPegasus:CQLParser_QueryCapabilities";
ElementName
= "Implemented CQL Features: Basic Query (2), Embedded Properties (8),
";
CQLFeatures
= { "2",”8" };
};
CQL query support is essential for CIM indications, and it will be the base for filtered associations in future, which are needed if dealing with a large number of CIM objects as the case for management of enterprise-class server environments. In contrast to WQL, CQL is formally specified, giving it long-term advantages with regard to interoperability.
Pegasus 2.5
SELECT * FROM CIM_InstModification WHERE SourceInsance ISA
CIM_ConcreteJob AND SourceInstance.OperationalStatus = 17
AND SourceInstance.OperationalStatus = 2.
The corresponding query in CQL (using Basic Query feature) would be:
SELECT * FROM CIM_InstModification WHERE
CIM_InstModification.SourceInstance._CLASSPATH
= 'CIM_ConreteJob' AND NOT
CIM_InstModification.SourceInstance.OperationalStatus[*]
= 17 AND NOT
CIM_InstModification.SourceInstance.OperationalStatus[*] = 2
If
this PEP will support 'Individual Array Elements' feature, the above query can
be improved as:
SELECT * FROM CIM_InstModification WHERE
CIM_InstModification.SourceInstance._CLASSPATH
= 'CIM_ConreteJob' AND
CIM_InstModification.SourceInstance.OperationalStatus[0]
=
17 AND CIM_InstModification.SourceInstance.OperationalStatus
[1] = 2
The logic is simpler, so the time to process the second query could be faster.
However, there is still no obvious way to verify the array length. Therefore
the
OperationalStatus[*] could be {17,2} or {17,2,6}.
OB> Unfortunately, such a query is beyond the scope of this PEP. We are
missing array support and support for embedded objects.
BTW, the 'symbolic constants' sounds like a handy feature. I am wondering if
this PEP will support it or not.
(andreas_maier)(1) I
suggest to rebase this PEP whenever the next CQL Spec after V0.11
comes out (probably V0.12). Reason is that the ABNF should be error free by
then, and the Basic Query support should be precisely identifiable then. (2)
This sentence states that this PEP also provides ExecuteQuery support. Further
down in this PEP, this is contradicted. Resolve.
[ (dong_xiang) It seems not all features in the 'Basic Query'
are supported in this PEP. Please specify in details what is supported and what
is not.
(andreas_maier) (1) Once V0.12 of the CQL Spec is out, I expect that the Basic
Query functionality is precisely defined there, so we do not need to repeat it
in this PEP. (2) In V0.11, there are two features with LIKE: 'Basic Like' and
'Full Like'. Specify which of these we plan to support.
[ (dong_xiang) We definitely need to address embedded objects
and specific array elements in the WHERE clause as a minimum. Would you please
tell us how hard to have a support for these features and what is your concern
if we include these features in the PEP?
[ ¤75] Join operations
[ (andreas_maier)
This point refers to the CQL feature 'Satisfies Array', in addition to 'Array
Elements'. I suggest to list the excluded features by
the feature names as per the CQL Spec.
¤76] Array operations,
so array properties may not appear anywhere in the query, regardless whether
used with constant or with *
[ (andreas_maier)
I have to correct my initial comment. There is still some ambiguity in the CQL
Spec V0.11 regarding the behaviour of Basic Query on Embedded Objects. I tend
to believe that the embedded capabilities of Basic Query are not sufficient for
purposes of indications and event based monitoring, so that we would need to
support the feature Embedded Objects. I'll clarify that.
¤77] Embedded objects
in whatever form in the query
[ (andreas_maier)
Support for URI-REFERENCE (i.e. [class-path] in the [class-identifier]) is part
of Basic Query, as per the CQL Spec V0.11. I suggest to
implement the complete Basic Query.
¤78] WBEM URI
specification (DSP0207)
[ (andreas_maier)
Also no support for path functions
¤79] Aggregation
function
[ ¤80] Subqueries
[ (andreas_maier)
Support for Qualifiers is part of Basic Query, as per the CQL Spec V0.11. I
suggest to implement the complete Basic Query.
¤81] Qualifiers
[ (andreas_maier) In addition to this exclusion list, the
following CQL features are also meant to be excluded, I guess: 'Order By',
'Distinct', 'First' and 'Full Like'. Please confirm.
OB>
I have listed above that first stage of query feature "Basic Query",
plus, "Time", "Basic Like" and (for non-Windows) "Full
Like" are to be implemented. This list is just to make it more precise.
[ (andreas_maier)DMTF did not 'remove support for WQL'. This
statement is inrorrect and should be removed.
(chuck_carmack) This is an important discussion point. The proposal is to only
do bug fixes on WQL.
[ (andreas_maier)I suggest to implement the complete 'Basic
Query'. By V0.12 of trhe CQL Spec, it should be sufficiently stable. We are already
now only iterating on how to present it in the ABNF, the contents already now
(V0.11) seems to be stable.
[ (andreas_maier)
Don't repeat the regexp definition, you are already referring to the respective
section of the CQL Spec.
[ (andreas_maier) The CQL Spec prescribes CIM_ERR_INVALID_QUERY
to be returned in this case.
[ (andreas_maier) Do we suggest to implement it as part of this
PEP ?
(chuck_carmack) That was my question too. Do we need a provider for this? If we
do, then what do we declare as the supported level of CQL?
[ (chuck_carmack) A static instance is obviously easier, but
having any static instances in the repository is a discussion point.
carolann_gravesThis PEP should also specify what
Filter QueryLanguage
string value will be supported, e.g. 'CQL'? For
interoperability, the Filter QueryLanguage value should be
consistent with that used by other CIM Server
implementations.
carolann_gravesJust to clarify, if an array property
is specified without
brackets in the query (e.g. SELECT CorrelatedIndications
FROM CIM_ProcessIndication; or SELECT * FROM
CIM_ProcessIndication), the error would not be caught by
the parser, but would be caught later on, right?
carolann_gravesmissing '7'
[ (carolann_graves)
Instead of specifying a particular version (which becomes superseded), it would
be great to include a generic statement that the expectation is that the CQL
spec will be final before the pegasus release, and that the intention is for
the functionality to be consistent with the final CQL spec. (See also tag 145.)
¤128] Abstract: This PEP proposes the
implementation of a subset of CQL for indication filter strings (event based
monitoring). It is based on "CIM Query Specification" (DSP0202)
Version 0.18.002 (September 2004).
OB> agreed, changed
[ ¤140] The assumption is that CQL and WQL will co-exist for
some while. However, WQL was never really standardized, and existing
implementations are not interoperable. In order to use CQL, the queryLanguage
string has to be "CQL".
[ (carolann_graves)
This statement is out of sync with the statement in PEP 193 ('CIM:CQL').
Perhaps it doesn't need to be stated here, and can just appear in PEP 193.
OB> agreed, changed
Comments submitted by: chuck_carmack.
Document Title: .
File: pep138_cqlstage1_10.htm. Tag: 148. Action = insert
Comment:
PEP 194 is the subsequent PEP to 158
Copyright (c) 2004 EMC
Corporation; Hewlett-Packard Development Company, L.P.; IBM Corp.; The Open
Group; VERITAS Software Corporation
Permission
is hereby granted, free of charge, to any person obtaining a copy of this
software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
THE
ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN ALL
COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Template last
modified: January 20th 2004 by Martin Kirk
Template version: 1.6