6.7.6SHOW
Syntax
SHOW [GROUP | DATASET | ATTRIBUTE | [SOFT] LINK | EXTERNAL LINK] [[file_name] object_name] [LIKE regular_expression [DEEP {deep_value | {[deep_value] {, [deep_value]}+}}]
[WHERE condition]
[BY CREATION ORDER]
[post_processing_option]
[output_redirecting_option]
condition := [NOT]* {type | data_type | (condition)} [{AND | OR} [NOT]* {type | data_type | (condition)}]*
type := TYPE {== | !=} {GROUP | DATASET | ATTRIBUTE | [SOFT] LINK | EXTERNAL LINK}
data_type := DATA TYPE {== | !=} {TINYINT | UNSIGNED TINYINT | SMALLINT | UNSIGNED SMALLINT | INT | UNSIGNED INT | BIGINT | UNSIGNED BIGINT | FLOAT | DOUBLE | CHAR | VARTINYINT | UNSIGNED VARTINYINT | VARSMALLINT | UNSIGNED VARSMALLINT | VARINT | UNSIGNED VARINT | VARBIGINT | UNSIGNED VARBIGINT | VARFLOAT | VARDOUBLE | VARCHAR | OPAQUE | ENUMERATION | COMPOUND}
Description
Show (i.e. get) the HDF5 objects (i.e. groups, datasets, attributes, (soft) links, and external links) within an HDF5 group or dataset named object_name or check for the existence of an object named object_name. If object_name is not specified, all objects within the HDF5 group currently in use are returned. To return only objects of type group, dataset, attribute, (soft) link, or external link, specify the keyword GROUP, DATASET, ATTRIBUTE, [SOFT] LINK, or EXTERNAL LINK, respectively. Otherwise, if object_name is specified and the keyword LIKE is not specified, one of the following behaviors applies:
- If it ends with “/”, object_name will be treated as a group or dataset, and all groups, datasets, or attributes stored in object_name are returned.
- If it does not end with “/”, object_name will be checked for existence. If it exists, object_name is returned; otherwise, if it does not exist, an error is raised.
In case the keyword LIKE is specified, only objects with names complying with a regular expression named regular_expression will be returned (in HDFql, regular expressions are the ones specified by PCRE, which closely follows Perl 5 syntax – please refer to https://www.pcre.org and https://perldoc.perl.org/perlre for additional information). As a general rule, in case regular_expression contains spaces or special characters, it should be enclosed in double quotes (“). Otherwise, if it is not enclosed in double quotes, objects are not returned, and an error is raised. If regular_expression includes “**”, a recursive search is performed (i.e. HDFql will search in all existing groups and subgroups for objects to return). If object_name is specified, the recursive search starts from within object_name, which is assumed to be a group or a dataset. To limit the recursiveness, the keyword DEEP may be specified along with a value deep_value that represents the maximum recursiveness limit.
A special type of ordering can be performed using the keyword BY CREATION ORDER, allowing HDF5 objects (i.e. groups, datasets, attributes, (soft) links, and external links) to be returned according to their time of creation46 – in contrast to the default behavior, which returns objects in an ascending order.
Parameter(s)
file_name – optional string that specifies the name of the HDF5 file storing the objects (i.e. groups, datasets, attributes, (soft) links, and external links) to show (i.e. get) or to check for their existence. If file_name is specified, the file is opened on the fly, the objects are obtained or checked for their existence, and the file is subsequently closed. If not specified, the file currently in use is used instead.
object_name – optional string that specifies the name of the HDF5 object within which to show (i.e. get) existing objects (i.e. groups, datasets, attributes, (soft) links, and external links) or to check for the existence of the object.
regular_expression – optional string that specifies the regular expression with which the names of objects must comply for those objects to be returned. If regular_expression includes “**”, a recursive search is performed.
deep_value – optional integer that specifies the maximum recursiveness limit (i.e. how deep the recursive search is performed). If deep_value is specified, it must be equal to or greater than 0 (otherwise an error is raised).
condition – to be defined.
post_processing_option – optional option that transforms the result set according to the programmer’s needs, such as ordering or truncating (please refer to the section PROCESSING for additional information).
output_redirecting_option – optional option that specifies the cursor in use, an HDF5 object (i.e. dataset or attribute), a (text, binary, or Excel) file, or memory (i.e. user-defined variable) to write the result set into (please refer to the subsection INTO for additional information). If not specified, the cursor in use is populated with the result set instead (please refer to the chapter CURSOR for additional information).
Return
The HDF5 objects (i.e. groups, datasets, attributes, (soft) links, and external links) within an HDF5 group or dataset or the existence of an object as an HDFQL_VARCHAR.
Example(s)
# set group currently in use to "/" (i.e. the root of the HDF5 file)
USE GROUP /
# create two HDF5 groups named "my_group0" and "my_group1" (both groups will be created in group "/")
CREATE GROUP my_group0, my_group1
# create one HDF5 dataset named "my_dataset0" of data type unsigned short (it will be created in group "/")
CREATE DATASET my_dataset0 AS UNSIGNED SMALLINT
# create one HDF5 dataset named "my_dataset1" of data type short (it will be created in group "/my_group0")
CREATE DATASET my_group0/my_dataset1 AS SMALLINT
# create two HDF5 attributes named "my_attribute0" and "my_attribute1" of data type long long (both attributes will be created in group "/")
CREATE ATTRIBUTE my_attribute0, my_attribute1 AS BIGINT
# create one HDF5 attribute named "my_attribute2" of data type char (it will be created in group "/my_group0")
CREATE ATTRIBUTE my_group0/my_attribute2 AS TINYINT
# create one HDF5 attribute named "my_attribute3" of data type unsigned char (it will be created in dataset "/my_dataset0")
CREATE ATTRIBUTE my_dataset0/my_attribute3 AS UNSIGNED TINYINT
# show (i.e. get) all HDF5 objects existing in group "/" (should return "my_group0", "my_group1", "my_dataset0", "my_attribute0", "my_attribute1")
SHOW
# show (i.e. get) all HDF5 groups existing in group "/" (should return "my_group0", "my_group1")
SHOW GROUP
# show (i.e. get) all HDF5 datasets existing in group "/" (should return "my_dataset0")
SHOW DATASET
# check if HDF5 object "my_groupX" exists (should raise an error)
SHOW my_groupX
# check if HDF5 object "my_group0" exists (should return "my_group0")
SHOW my_group0
# show (i.e. get) all HDF5 objects existing within group "my_group0" (should return "my_dataset1", "my_attribute2")
SHOW my_group0/
# show (i.e. get) all HDF5 attributes existing within group "my_group0" (should return "my_attribute2")
SHOW ATTRIBUTE my_group0/
# show (i.e. get) all HDF5 objects existing within dataset "my_dataset0" (should return "my_attribute3")
SHOW my_dataset0/# create an HDF5 group named "my_group1" that tracks the objects’ creation order (i.e. groups and datasets) within the group
CREATE GROUP my_group1 ORDER TRACKED
# create two HDF5 groups named "my_subgroup1" and "my_subgroup0" (both groups will be created in group "/my_group1")
CREATE GROUP my_group1/my_subgroup1, my_group1/my_subgroup0
# create two HDF5 datasets named "my_dataset1" and "my_dataset0" of data type float (both datasets will be created in group "/my_group1")
CREATE DATASET my_group1/my_dataset1, my_group1/my_dataset0 AS FLOAT
# show (i.e. get) all HDF5 objects existing within group "my_group1" (should return "my_dataset0", "my_dataset1", "my_subgroup0", "my_subgroup1")
SHOW my_group1/
# show (i.e. get) all HDF5 objects existing within group "my_group1" ordered by their time of creation (should return "my_subgroup1", "my_subgroup0", "my_dataset1", "my_dataset0")
SHOW my_group1/ BY CREATION ORDER
# create an HDF5 dataset named "my_dataset1" of data type double that tracks the attributes’ creation order within the dataset
CREATE DATASET my_dataset1 AS DOUBLE ATTRIBUTE ORDER TRACKED
# create two HDF5 attributes named "my_attribute2" and "my_attribute0" of data type int (both attributes will be created in dataset "/my_dataset1")
CREATE ATTRIBUTE my_dataset1/my_attribute2, my_dataset1/my_attribute0 AS INT
# create an HDF5 attribute named "my_attribute1" of data type short (it will be created in dataset "/my_dataset1")
CREATE ATTRIBUTE my_dataset1/my_attribute1 AS SMALLINT
# show (i.e. get) all HDF5 objects existing within dataset "my_dataset1" (should return "my_attribute0", "my_attribute1", "my_attribute2")
SHOW my_dataset1/
# show (i.e. get) all HDF5 objects existing within dataset "my_dataset1" ordered by their time of creation (should return " my_attribute2", "my_attribute0", "my_attribute1")
SHOW my_dataset1/ BY CREATION ORDER
# create an HDF5 group named "my_group2"
CREATE GROUP my_group2
# create two HDF5 groups named "my_subgroup0" and "my_subgroup1" (both groups will be created in group "/my_group2")
CREATE GROUP my_group2/my_subgroup0, my_group2/my_subgroup1
# create three HDF5 groups in one go named "my_group3" (in root "/"), "my_subgroup0" (in group "my_group3") and "my_subsubgroup0" (in group "my_group3/my_subgroup0")
CREATE GROUP my_group3/my_subgroup0/my_subsubgroup0
# create an HDF5 dataset named "my_dataset2" (in root "/") of data type double
CREATE DATASET my_dataset2 AS DOUBLE
# create an HDF5 dataset named "my_dataset0" (in group "my_group2") of data type int
CREATE DATASET my_group2/my_dataset0 AS INT
# create an HDF5 dataset named "my_dataset1" (in group "my_group2") of data type short
CREATE DATASET my_group2/my_dataset1 AS SMALLINT
# create an HDF5 dataset named "my_dataset0" (in group "my_group3") of data type float
CREATE DATASET my_group3/my_dataset0 AS FLOAT
# create an HDF5 dataset named "my_dataset0" (in group "my_group3/my_subgroup0") of data type char
CREATE DATASET my_group3/my_subgroup0/my_dataset0 AS TINYINT
# create an HDF5 attribute named "my_attribute3" (in group "/") of data type long long
CREATE ATTRIBUTE my_attribute3 AS BIGINT
# create an HDF5 attribute named "my_attribute4" (in group "/") of data type unsigned int
CREATE ATTRIBUTE my_attribute4 AS UNSIGNED INT
# create two HDF5 attributes in one go that are both named "my_attribute0" (one in group "my_group2" and the other in "my_group3") of data type variable float
CREATE ATTRIBUTE my_group2/my_attribute0, my_group3/my_attribute0 AS VARFLOAT
# create an HDF5 attribute named "my_attribute0" (in dataset "my_dataset2") of data type variable-length char
CREATE ATTRIBUTE my_dataset2/my_attribute0 AS VARCHAR
# show (i.e. get) all HDF5 objects from group "/" that have "3" in their names (should return "my_attribute3", "my_group3")
SHOW LIKE 3
# show (i.e. get) all HDF5 attributes from group "/" that has "3" in their names (should return "my_attribute3")
SHOW ATTRIBUTE LIKE 3
# show (i.e. get) all HDF5 objects recursively starting from group "/" (should return "my_attribute3", "my_attribute4", "my_dataset2", "my_dataset2/my_attribute0", "my_group2", "my_group2/my_attribute0", "my_group2/my_dataset0", "my_group2/my_dataset1", "my_group2/my_subgroup0", "my_group2/my_subgroup1", "my_group3", "my_group3/my_attribute0", "my_group3/my_dataset0", "my_group3/my_subgroup0", "my_group3/my_subgroup0/my_dataset0", "my_group3/my_subgroup0/my_subsubgroup0")
SHOW LIKE **
# show (i.e. get) all HDF5 datasets recursively starting from group "/" (should return "my_dataset2", "my_group2/my_dataset0", "my_group2/my_dataset1", "my_group3/my_dataset0", "my_group3/my_subgroup0/my_dataset0")
SHOW DATASET LIKE **
# show (i.e. get) all HDF5 datasets recursively starting from group "/" and one level deep at most (should return "my_dataset2", "my_group2/my_dataset0", "my_group2/my_dataset1", "my_group3/my_dataset0")
SHOW DATASET LIKE ** DEEP 1
# show (i.e. get) all HDF5 objects recursively starting from group "my_group3" (should return "my_attribute0", "my_dataset0", "my_subgroup0", "my_subgroup0/my_dataset0", "my_subgroup0/my_subsubgroup0")
SHOW my_group3 LIKE **
# show (i.e. get) all HDF5 groups recursively starting from group "my_group3" (should return "my_subgroup0", "my_subgroup0/my_subsubgroup0")
SHOW GROUP my_group3 LIKE **
# show (i.e. get) all HDF5 objects recursively starting from group "/" that has "2" in their names (should return "my_dataset2", "my_group2")
SHOW LIKE **/2
# show (i.e. get) all HDF5 groups recursively starting from group "/" that has "1" or "2" in their names (should return "my_group2", "my_group2/my_subgroup1")
SHOW GROUP LIKE **/1|2
# show (i.e. get) all HDF5 objects recursively starting from group "/" that starts with "sub" in their names (should return "my_group2/my_subgroup0", "my_group2/my_subgroup1", "my_group3/my_subgroup0", "my_group3/my_subgroup0/my_subsubgroup0")
SHOW LIKE **/^my_sub# use (i.e. open) an HDF5 file named "my_file.h5"
USE FILE my_file.h5
# create an HDF5 group named "my_group3" in the HDF5 file currently in use (i.e. file "my_file.h5")
CREATE GROUP my_group3
# create two HDF5 datasets named "my_dataset3" and "my_dataset4" of data type double both in the HDF5 file currently in use (i.e. file "my_file.h5")
CREATE DATASET my_dataset3, my_dataset4 AS DOUBLE
# show (i.e. get) all HDF5 objects existing in group "/" of the HDF5 file currently in use (i.e. file "my_file.h5") (should return "my_group3", "my_dataset3", "my_dataset4")
SHOW /
# close HDF5 file currently in use (i.e. file "my_file.h5")
CLOSE FILE
# show (i.e. get) all HDF5 objects existing in group "/" of file "my_file.h5" (should return "my_group3", "my_dataset3", "my_dataset4")
SHOW my_file.h5 /Notes
- This assumes that the HDF5 group or dataset storing the objects was created with the option of tracking objects by their time of creation. Otherwise, if the group or dataset was not created with the option of tracking objects by their time of creation, the keyword BY CREATION ORDER is ignored (i.e. has no effect). Please refer to the CREATE GROUP and CREATE DATASET operations for additional information. ↩