Skip to content

Scope

This page explains how the scope parameter is used in query routing in kdb Insights.

The scope parameter is a distinguished request parameter that is used in routing decisions. It is similar to labels in that it determines the target Data Access Processes (DAPs) that service the request (see routing and labels), but it differs in that it also influences which Resource Coordinator (RC) is chosen by the Gateway (GW).

The scope parameter is specified in the request arguments as a dictionary. The keys in the dictionary determine which RC the GW chooses and which DAPs the RC ultimately chooses.

Key Type Description
assembly symbol Single package to target.
tier symbol Single Data tier to target. Supported only when scope.assembly is specified.
dap symbol Specific DAP to target. Supported only when scope.assembly is specified.
affinity symbol Affinity types:
  • soft: Prefers the resources in the target database, but falls back to global resource coordinators if none are available.>
  • hard: Restricts requests to resources in the target database. If it doesn't have its own resource coordinator, the request fails with a No resources connected error.
      • The effect of the assembly.affinity value depends on the endpoint, as shown below:
      Setting\qsqlAll other endpoints
      "affinity": "soft"softsoft
      "affinity": "hard"hardhard
      "affinity": ""uses KXI_SCOPE_AFFINITYuses KXI_SCOPE_AFFINITY
      Omit affinitysoftuses KXI_SCOPE_AFFINITY
      Supported only when scope.assembly is specified.

Warning

When specifying a scope you cannot specify both scope.tier and scope.dap.

Dedicated vs Global querying resources

Resource Coordinators and Aggregators can be deployed in two ways depending on your use case:

  • Global: deployed in the base insights install. This is the default.

    Refer to the Query resources for details on their resource allocation.

  • Dedicated: deployed as part of a package.

    You may wish to use dedicated resources for certain database when queries need to be highly available and not have to wait behind all the other queries that are running against the global resources.

    You can add dedicated RCs and Aggs to your package using the kxi package add command as follows:

    kxi package add --to db-package agg
kxi package add --to db-package rc

Gateway to Resource Coordinator

The scope parameter is specified in the request arguments. For example:

gw:hopen`:gateway_host:1234 # Open connection to GW
gw(`.kxi.getData;`table`scope!(`myTable;enlist[`assembly]!enlist`myAssembly);`;()!()) # Target "myAssembly"

If scope is specified, the Service Gateway attempts to send the request to an RC in the target package. If no RC is found and scope.assembly is configured to use the KXI_SCOPE_AFFINITY environment variable, then:

  • If KXI_SCOPE_AFFINITY="hard" (default), then the request fails immediately with a No resources connected error.
  • If KXI_SCOPE_AFFINITY="soft", then the GW sends to a global RC, and that RC is then responsible for routing to DAPs of the correct package.

If the scope parameter is not specified in the request arguments, the GW targets one of the global RCs.

Data tiers

Data tiers are described under the daps key of the shard file within a package. The existing tiers are defined as follows:

  • The instances names, if the scaling configuration is of type mountName.
  • The names contained within the mountList, if the scaling configuration is of type mountList.

See scaling-configurations for details.

All available tiers are listed in getMeta.dap under the instance column.

Warning

The .scope.tier parameter is not supported by .kxi.sql. Attempting such a request fails with a "Invalid scope, tier - nyi" error.

DAPs

Can target individual DAPs via scope.dap option. All available DAPs are listed in getMeta.dap under the dap column when the advanced option is set as true.

Warning

The .scope.dap parameter is not supported by .kxi.sql. Attempting such a request will fail with a Invalid scope, dap - nyi error.

Back to top