The Tours of the Black Prompt series so far:

• NetApp Data ONTAP 7-Mode
  • Command line interface (CLI) overview including
    • Commands and Privilege Levels
    • Command Syntax and Help
    • Navigation and Editing
• Clustered NetApp Data ONTAP – Part 1 
  • CLI overview including
    • Commands, Navigation, and Privilege Levels
    • Command Syntax and Help
    • Command Completion
    • Navigation and Editing
• Clustered NetApp Data ONTAP – Part 2
  • Working with Command History
  • Setting Display Preferences
• Clustered NetApp Data ONTAP – Part 3
  • Field Options
  • Field Filtering
  • Queries and Operators

Today we’re continuing our look at more advanced CLI operations for clustered Data ONTAP with the use of extended queries.

Extended Queries

You specify an extended query by enclosing it within curly braces: “{}”. Extended queries are similar to standard queries and use the same operators, but there are some distinct differences in how and when you use each type of query. Show commands can be run with standard queries, while modify or delete commands can be run with either standard or extended queries (but not both).  Extended queries can be used to filter on parameters that a modify command is capable of changing, whereas standard queries can only be used for parameters that do not get changed with a modify command (most commonly, these are name parameters associated with vservers, volumes, aggregates, etc.). Neither type of query can be used with create commands.

Let’s look at some examples of how you can use modify commands with standard and extended queries.

With standard queries you can use multiple instances within the same command. In this case, we’ll thin-provision all volumes on all SVMs except for vol0:

cdot_mba1::> volume modify -vserver * -volume !vol0 -space-guarantee none  

Volume modify successful on volume: black_root

Volume modify successful on volume: avol1

Volume modify successful on volume: citrixvol1

Volume modify successful on volume: dept1_share

Volume modify successful on volume: dept2_share

Volume modify successful on volume: testvol1

Volume modify successful on volume: tours_root

Volume modify successful on volume: user_share

Volume modify successful on volume: vmwarevol1
9 entries were modified.

We can accomplish something similar using a single extended query instead:

cdot_mba1::> volume modify {-volume !vol0} -space-guarantee none

Volume modify successful on volume: black_root

Volume modify successful on volume: avol1

Volume modify successful on volume: citrixvol1

Volume modify successful on volume: dept1_share

Volume modify successful on volume: dept2_share

Volume modify successful on volume: testvol1

Volume modify successful on volume: tours_root

Volume modify successful on volume: user_share

Volume modify successful on volume: vmwarevol1
9 entries were modified.

You can’t use both a standard query and an extended query within the same command, nor can you use more than one extended query in a single command:

cdot_mba1::> volume modify {-volume !vol0} -vserver * -space-guarantee none

Error: invalid argument "-vserver"

cdot_mba1::> volume modify {-volume !vol0} {-vserver *} -space-guarantee none

Error: "-vserver *" was not expected. Please specify -fieldname first.

As seen in our first extended query example above, an extended query must always be the first argument after the command before any other parameters are specified.

cdot_mba1::> volume modify -vserver tours {-volume !vol0} -space-guarantee none

Error: Volume name: The first character must be a letter or underscore.

An extended query can also not be used with subsequent filtering parameters (such as volume names, SVM names, etc.) even when specifying their values rather than using standard queries:

cdot_mba1::> volume modify {-volume !vol0} -vserver tours -space-guarantee none

Error: invalid argument "-vserver"

The inverse is also true: with extended queries, you don’t need to specify additional parameters that you may need to include when using standard queries:

cdot_mba1::> volume modify -volume !vol0  -space-guarantee none              

Error: Either specify all keys, or set at least one key to "*".

cdot_mba1::> volume modify -volume !vol0 -vserver tours -space-guarantee none

Volume modify successful on volume: avol1

Volume modify successful on volume: citrixvol1

Volume modify successful on volume: dept1_share

Volume modify successful on volume: dept2_share

Volume modify successful on volume: testvol1

Volume modify successful on volume: tours_root

Volume modify successful on volume: user_share

Volume modify successful on volume: vmwarevol1
8 entries were modified.

cdot_mba1::> volume modify {-volume !vol0}  -space-guarantee volume

Volume modify successful on volume: black_root

Volume modify successful on volume: avol1

Volume modify successful on volume: citrixvol1

Volume modify successful on volume: dept1_share

Volume modify successful on volume: dept2_share

Volume modify successful on volume: testvol1

Volume modify successful on volume: tours_root

Volume modify successful on volume: user_share

Volume modify successful on volume: vmwarevol1
9 entries were modified.

You can always tell if what you’re trying to do is going to work or not simply by trying to tab-complete. If the syntax is correct, you will be able to tab-complete commands within the extended query (between the curly braces) and after it; if your syntax is incorrect, you will not.

Putting It All Together

The combination of standard and extended queries provide a lot of power and efficiency for modifying storage configurations. Here’s just a few simple examples using the volume and lun commands:

Change the size of volumes matching a certain naming pattern

cdot_mba1::> volume modify {*share} -size +20M  

Volume modify successful on volume: dept1_share

Volume modify successful on volume: dept2_share

Volume modify successful on volume: user_share
3 entries were modified.

Change the size of volumes matching a certain current size

cdot_mba1::> volume modify {-size 40M} -size 20M

Volume modify successful on volume: dept1_share

Volume modify successful on volume: dept2_share

Volume modify successful on volume: user_share
3 entries were modified.

As noted in the System Administration Guide, you do need to be careful when modifying the same parameter that you are using for the queries as there can be unintended consequences as the command processes.

Modify the space guarantee settings for a volume based on its policy type

For example, you may want to do this to ensure that all of your virtualization volumes are thin provisioned.

cdot_mba1::> volume modify {-policy esx_exports} -space-guarantee none

Volume modify successful on volume: vmwarevol1
1 entry was modified.

Map a LUN to an Initiator Group based on its OS type

cdot_mba1::> lun map {-ostype vmware} -igroup esx
2 entries were acted on.

---

The examples we’ve been using in this series so far have all been fairly simple with the actual CLI output run and validated on a simulator on my laptop. In a forthcoming post I’ll go through some more sophisticated examples from real  projects and technical documentation that I’ve been worked on over the last year.

Stay tuned.