Chapter 5 Programming Considerations and Best Practices

This chapter provides considerations and practices that can help you create efficient 5800 system applications.

The following topics are discussed:

• Retries and Timeouts

• Query Size Limit

• Limit the Size of Schema Query Parameters and Literals

• Limit Results Per Fetch

Retries and Timeouts

Client applications should place API calls within retry loops to handle cases such as storage node failover. One immediate retry should be sufficient in the great majority of cases. In some cases of node failover, retries should be pursued for up to 30 seconds.

When the 5800 system server is sufficiently loaded, client timeouts may occur. To avoid this, maximum client threads should no greater than 25 times the number of nodes. For example, on a full-cell with 16 storage nodes, the maximum client threads should be less than or equal to 25 times 16, or 400 client threads.

Query Size Limit

There is a hard limit when querying a live 5800 system or hive on the combined size of query parameters and literal values that can be processed in one query. The limit is slightly over 8000 bytes. The query string itself does not count against this limit, just the parameter and literal values in the query.

Each additional parameter or literal in the query contributes 2 bytes of overhead plus the number of bytes to represent the query value. For this calculation, each date or time value consumes 4 bytes. Each long, double, or timestamp value consumes 8 bytes. A binary or char field consumes the same number of bytes as the length of the value. A string value consumes twice as many bytes as the length of the value. These sizes are similar to what is described in the Sun StorageTek 5800 System Administration Guide, Table 7-6, Number of Bytes Used by Each Element Type in a Schema Table.

For example, assume dynamic parameter 1 is bound to string "Hello" in the query system.test.type_string=?. The parameter length would then be 12 bytes: 2 bytes overhead plus 10 bytes for a 5-character string parameter.

Conversely, note that in the query system.test.type_string like '%Hello%' that the parameter is 16 bytes: 2 bytes overhead plus 14 bytes for a 7 character string regardless of the declared size of the system.test.type_string field in the schema.

For the query system.test.type_date = {date '2007-01-1'} AND system.test.type_char='Hello', the parameter length is 13 bytes: 2 bytes overhead for each of two query values plus 4 bytes for a date literal plus 5 bytes for a 5-character char parameter.

Limit the Size of Schema Query Parameters and Literals

When designing a schema, limit the sizes of fields so that planned queries will fit within the size limits. Most simple queries on a single table will fit within the 8000-byte limit. This is because the table row definition itself must fit within the similar 8080-bytes for overall table row size. Also note that complex queries on even a single table (such as queries involving many OR clauses) may overflow the limit. Schema design and query design must work together carefully if complex queries are an important part of the application.

For further information, see Query Size Limit.

Limit Results Per Fetch

Queries should use a reasonable value of “results per fetch” when a large total result set size is expected. The maximum result size should not exceed the memory allocated for the query engine on the server side. If it does, then the query will fail. Dropping the query result size will allow the query to succeed.

If you incorrectly estimate how much memory will be used by the result set, the server will not fail gracefully with an appropriate error message, but will instead run out of memory.

Suggested values are in the 2000-5000 range. Set maxFetchSize = 4098 as an argument to the query method.