The table Command: Subtables

With version 10.1, we've given the session table some long-sought functionality, and revamped its iRules interface completely to give users a new, cleaner, full-featured way to keep track of global data. We are very proud to introduce the table command...

  1. Basics
  2. New Ways To Set Data
  3. New Ways To Alter Data
  4. Data Expiration
  5. Advanced Data Expiration
  6. Subtables
  7. Counting
  8. The Fine Print
  9. Examples

In this sixth part of the series on the usage of the new table command, we discuss how you can create and manage subtables within the session table.


Whew! Still with me? Good, because we're just now getting to some of best stuff.

One of the most powerful changes to the session table in v10.1 is the concept of a subtable, which is simply a named set of entries. It lets you organize your entries in groups, and lets you act on those groups.  A subtable is basically a table in and of itself, with some special abilities. Subtables only contain entries, though; you can’t nest subtables. Here's what they look like:

They are trivial to use: every current table subcommand simply takes a -subtable <name> parameter. So you can do things like:

table set -subtable $tbl $key $data
table lookup -subtable $othertbl $key
table delete -subtable $thirdtbl $key

That's all there is to it! Doesn't look like much, does it? But this is very powerful stuff! Maybe you want a different set of data for each user, or for each client IP address, or for each virtual server? No problem!

table set -subtable "$username" $key $data
table add -subtable "[IP::client_addr]" $key $data
table replace -subtable "[virtual]" $key $data

Since you can name your subtables however you want, you can now have shared variables with any arbitrary scope! And there's an easy way to clean up:

table delete -all -subtable "$username"

will remove every entry in a subtable in one fell swoop.

But wait! There's more!

With subtables comes a new and long-desired ability: the ability to list or count the number of keys:

table keys -subtable <name> [-count|-notouch]

You’ll note that unlike all the other table subcommands, the subtable name is not optional here: there’s no way to use it on entries that aren’t in a subtable. Also note that by default, retrieving the list of keys will touch each one, but getting the count will never touch any entries.

Isn't this AWESOME!?! This feature is going to simplify a lot of your iRules, and give you the ability to do things that simply weren't feasible before. I can't wait to see all the creative uses you come up with!

That covers all of the new session table features. Now we'll cover some ways of putting everything together...

Continue reading part seven in our series: Counting

Published Jan 13, 2010
Version 1.0

Was this article helpful?


  • This may be a silly question, but can the subtable hold multiple key/value pairs?





    Subtable: DNS



    Key | Value



    user77 | 5254


    user78 | 5100


    user79 | 5300



  • spark_86682's avatar
    Historic F5 Account
    Absolutely. Subtables can hold as many keys and values as you have memory for.
  • So -subtable parameter just gives name for table and it does not have anything to do with main table (without -subtable argument). ? So I can think that -subtable means actually -table (although parameter is not that)



    that is: it is not nested table.



    ( keys on table are not on relation on keys of main (unnamed) table )




    / Kari Hurtta




  • spark_86682's avatar
    Historic F5 Account
    Given the currently available commands, you could think of a subtable as just a named table, yes. We did consider calling that parameter "-name" and presenting them exactly as named tables, in fact. However, the way they are implemented is much closer to the presentation you see here: all of the data in a subtable is actually present as part of the main table. This may matter in the future as more features are added (for example, we may someday support nested subtables), so it was decided to present the functionality as "subtables".
  • Jeremiah_Fowle2's avatar
    Historic F5 Account
    I have a question in regards to performing table lookups. The article is well constructed data setting is well documented, however data lookups I'm having an issue finding clear detail. I am wanting to create a table via one virtual with a key that is the client IP address, and a value of a jsessionid. I want to then walk the table via a different iRule and find and compare the key to the data. I am having some issues on how to perform this function. I've also considered making the key both a combination of the client IP and jsessionid. Any pointers would be greatly appreciated.