Hostname and IP address considerations for paged queries
For operation-based queries, HCP caches each query for a period of time on the node that receives the request. If you use an IP address in the URL in each request, you access the cached query and avoid having to recreate the query with each request. This can significantly improve the performance of paged queries that return metadata for large numbers of objects.
Some HTTP libraries cache HTTP connections. Programs using these libraries may automatically reconnect to the same node for paged queries. In this case, using a hostname to establish the connection provides the same performance benefit as using an IP address.
Maximum concurrent queries
HCP nodes can each process a maximum of five concurrent queries. If a query arrives at a node that is currently processing five queries, HCP queues the query and processes it as soon as the current queries are complete. A 503 (Service Unavailable) error code is only returned if so many queries are queued up that the node fails to deal with them in the maximum allotted wait time.
In response to a 503 error code, you should try the query again, gradually increasing the delay between each successive attempt.
Query performance with object-based queries
For improved query performance with object-based queries:
- Do not specify a true value for the verbose request entry.
- Specify the facets or sort request entries only when necessary.
- In the objectProperties entry, specify only urlName, objectPath, version, and changeTimeMilliseconds.
- When performing paged queries, specify a value of one hundred or less in the count request entry.
Queries based on object names
The metadata query API relies on UTF-8 encoding conventions to find objects by name. If the name of an object is not UTF-8 encoded, queries for the object by name may return unexpected results.
Queries specified namespaces
When you specify namespaces in query requests, responses to object-based queries differ from responses to operation-based queries in these situations:
- If you specify a namespace that doesn’t exist:
- In an object-based query, HCP returns zero results. If you specify both namespaces that exist and namespaces that don’t exist, HCP returns results for objects in the namespaces that exist.
- In an operation-based query, HCP returns a 400 (Bad Request) error.
- If you use a tenant-level user account and specify an HCP namespace for which you do not have search permission:
- In an object-based query, HCP returns zero results for the namespace.
- In an operation-based query, HCP returns a 403 (Forbidden) error.
- If you use a system-level user account and specify an HCP namespace owned by a tenant that has not granted administrative access to system-level users:
- In an object-based query, HCP returns zero results for the namespace.
- In an operation-based query, HCP returns a 403 (Forbidden) error.
HTTP status code considerations
Applications should account for all possible HTTP status codes for query requests.