YAML specification#

To generate a YAML configuration from a Flow Python object, use save_config().

YAML completion in IDE#

We provide a JSON Schema for your IDE to enable code completion, syntax validation, members listing and displaying help text.

PyCharm users#

Click menu Preferences -> JSON Schema mappings;
Add a new schema, in the Schema File or URL write https://api.jina.ai/schemas/latest.json; select JSON Schema Version 7;
Add a file path pattern and link it to *.jaml or *.jina.yml or any suffix you commonly used for Jina Flow’s YAML.

VSCode users#

Install the extension: YAML Language Support by Red Hat;
In IDE-level settings.json add:

"yaml.schemas": {
    "https://api.jina.ai/schemas/latest.json": ["/*.jina.yml", "/*.jaml"],
}

You can bind Schema to any file suffix you commonly used for Jina Flow’s YAML.

Example YAML#

jtype: Flow
version: '1'
with:
  protocol: http
executors:
# inline Executor YAML
- name: firstexec
  uses:
    jtype: MyExec
    py_modules:
      - executor.py
# reference to Executor YAML
- name: secondexec
  uses: indexer.yml
  workspace: /home/my/workspace
# reference to Executor Python class
- name: thirdexec
  uses: CustomExec  # located in executor.py

Fields#

`jtype`#

String that is always set to “Flow”, indicating the corresponding Python class.

`version`#

String indicating the version of the Flow.

`with`#

Keyword arguments are passed to a Flow’s __init__() method. You can set Flow-specific arguments and Gateway-specific arguments here:

Flow arguments#

Name	Description	Type	Default
`name`	The name of this object. This will be used in the following places: - how you refer to this object in Python/YAML/CLI - visualization - log message header - … When not given, then the default naming strategy will apply.	`string`	`None`
`workspace`	The working directory for any IO operations in this object. If not set, then derive from its parent `workspace`.	`string`	`None`
`log_config`	The YAML config of the logger used in this object.	`string`	`default`
`quiet`	If set, then no log will be emitted from this object.	`boolean`	`False`
`quiet_error`	If set, then exception stack information will not be added to the log	`boolean`	`False`
`uses`	The YAML path represents a flow. It can be either a local file path or a URL.	`string`	`None`
`reload`	If set, auto-reloading on file changes is enabled: the Flow will restart while blocked if YAML configuration source is changed. This also applies apply to underlying Executors, if their source code or YAML configuration has changed.	`boolean`	`False`
`env`	The map of environment variables that are available inside runtime	`object`	`None`
`inspect`	The strategy on those inspect deployments in the flow. If `REMOVE` is given then all inspect deployments are removed when building the flow.	`string`	`COLLECT`

Gateway arguments#

Name	Description	Type	Default
`name`	The name of this object. This will be used in the following places: - how you refer to this object in Python/YAML/CLI - visualization - log message header - … When not given, then the default naming strategy will apply.	`string`	`gateway`
`workspace`	The working directory for any IO operations in this object. If not set, then derive from its parent `workspace`.	`string`	`None`
`log_config`	The YAML config of the logger used in this object.	`string`	`default`
`quiet`	If set, then no log will be emitted from this object.	`boolean`	`False`
`quiet_error`	If set, then exception stack information will not be added to the log	`boolean`	`False`
`timeout_ctrl`	The timeout in milliseconds of the control request, -1 for waiting forever	`number`	`60`
`entrypoint`	The entrypoint command overrides the ENTRYPOINT in Docker image. when not set then the Docker image ENTRYPOINT takes effective.	`string`	`None`
`docker_kwargs`	Dictionary of kwargs arguments that will be passed to Docker SDK when starting the docker ‘ container. More details can be found in the Docker SDK docs: https://docker-py.readthedocs.io/en/stable/	`object`	`None`
`prefetch`	Number of requests fetched from the client before feeding into the first Executor. Used to control the speed of data input into a Flow. 0 disables prefetch (1000 requests is the default)	`number`	`1000`
`title`	The title of this HTTP server. It will be used in automatics docs such as Swagger UI.	`string`	`None`
`description`	The description of this HTTP server. It will be used in automatics docs such as Swagger UI.	`string`	`None`
`cors`	If set, a CORS middleware is added to FastAPI frontend to allow cross-origin access.	`boolean`	`False`
`no_debug_endpoints`	If set, `/status` `/post` endpoints are removed from HTTP interface.	`boolean`	`False`
`no_crud_endpoints`	If set, `/index`, `/search`, `/update`, `/delete` endpoints are removed from HTTP interface. Any executor that has `@requests(on=...)` bound with those values will receive data requests.	`boolean`	`False`
`expose_endpoints`	A JSON string that represents a map from executor endpoints (`@requests(on=...)`) to HTTP endpoints.	`string`	`None`
`uvicorn_kwargs`	Dictionary of kwargs arguments that will be passed to Uvicorn server when starting the server More details can be found in Uvicorn docs: https://www.uvicorn.org/settings/	`object`	`None`
`ssl_certfile`	the path to the certificate file	`string`	`None`
`ssl_keyfile`	the path to the key file	`string`	`None`
`expose_graphql_endpoint`	If set, /graphql endpoint is added to HTTP interface.	`boolean`	`False`
`protocol`	Communication protocol of the server exposed by the Gateway. This can be a single value or a list of protocols, depending on your chosen Gateway. Choose the convenient protocols from: [‘GRPC’, ‘HTTP’, ‘WEBSOCKET’].	`array`	`[<GatewayProtocolType.GRPC: 0>]`
`host`	The host address of the runtime, by default it is 0.0.0.0.	`string`	`0.0.0.0`
`proxy`	If set, respect the http_proxy and https_proxy environment variables. otherwise, it will unset these proxy variables before start. gRPC seems to prefer no proxy	`boolean`	`False`
`uses`	The config of the gateway, it could be one of the followings: * the string literal of an Gateway class name * a Gateway YAML file (.yml, .yaml, .jaml) * a docker image (must start with `docker://`) * the string literal of a YAML config (must start with `!` or `jtype:` ) * the string literal of a JSON config When use it under Python, one can use the following values additionally: - a Python dict that represents the config - a text file stream has `.read()` interface	`string`	`None`
`uses_with`	Dictionary of keyword arguments that will override the `with` configuration in `uses`	`object`	`None`
`py_modules`	The customized python modules need to be imported before loading the gateway Note that the recommended way is to only import a single module - a simple python file, if your gateway can be defined in a single file, or an `__init__.py` file if you have multiple files, which should be structured as a python package.	`array`	`None`
`grpc_server_options`	Dictionary of kwargs arguments that will be passed to the grpc server as options when starting the server, example : {‘grpc.max_send_message_length’: -1}	`object`	`None`
`graph_description`	Routing graph for the gateway	`string`	`{}`
`graph_conditions`	Dictionary stating which filtering conditions each Executor in the graph requires to receive Documents.	`string`	`{}`
`deployments_addresses`	JSON dictionary with the input addresses of each Deployment	`string`	`{}`
`deployments_metadata`	JSON dictionary with the request metadata for each Deployment	`string`	`{}`
`deployments_no_reduce`	list JSON disabling the built-in merging mechanism for each Deployment listed	`string`	`[]`
`compression`	The compression mechanism used when sending requests from the Head to the WorkerRuntimes. For more details, check https://grpc.github.io/grpc/python/grpc.html#compression.	`string`	`None`
`timeout_send`	The timeout in milliseconds used when sending data requests to Executors, -1 means no timeout, disabled by default	`number`	`None`
`runtime_cls`	The runtime class to run inside the Pod	`string`	`GatewayRuntime`
`timeout_ready`	The timeout in milliseconds of a Pod waits for the runtime to be ready, -1 for waiting forever	`number`	`600000`
`env`	The map of environment variables that are available inside runtime	`object`	`None`
`env_from_secret`	The map of environment variables that are read from kubernetes cluster secrets	`object`	`None`
`floating`	If set, the current Pod/Deployment can not be further chained, and the next `.add()` will chain after the last Pod/Deployment not this current one.	`boolean`	`False`
`reload`	If set, the Gateway will restart while serving if YAML configuration source is changed.	`boolean`	`False`
`port`	The port for input data to bind the gateway server to, by default, random ports between range [49152, 65535] will be assigned. The port argument can be either 1 single value in case only 1 protocol is used or multiple values when many protocols are used.	`number`	`random in [49152, 65535]`
`monitoring`	If set, spawn an http server with a prometheus endpoint to expose metrics	`boolean`	`False`
`port_monitoring`	The port on which the prometheus server is exposed, default is a random port between [49152, 65535]	`number`	`random in [49152, 65535]`
`retries`	Number of retries per gRPC call. If <0 it defaults to max(3, num_replicas)	`number`	`-1`
`tracing`	If set, the sdk implementation of the OpenTelemetry tracer will be available and will be enabled for automatic tracing of requests and customer span creation. Otherwise a no-op implementation will be provided.	`boolean`	`False`
`traces_exporter_host`	If tracing is enabled, this hostname will be used to configure the trace exporter agent.	`string`	`None`
`traces_exporter_port`	If tracing is enabled, this port will be used to configure the trace exporter agent.	`number`	`None`
`metrics`	If set, the sdk implementation of the OpenTelemetry metrics will be available for default monitoring and custom measurements. Otherwise a no-op implementation will be provided.	`boolean`	`False`
`metrics_exporter_host`	If tracing is enabled, this hostname will be used to configure the metrics exporter agent.	`string`	`None`
`metrics_exporter_port`	If tracing is enabled, this port will be used to configure the metrics exporter agent.	`number`	`None`

`executors`#

Collection of Executors used in the Flow. Each item in the collection corresponds to on add() call and specifies one Executor.

All keyword arguments passed to the Flow add() method can be used here.

Name	Description	Type	Default
`name`	The name of this object. This will be used in the following places: - how you refer to this object in Python/YAML/CLI - visualization - log message header - … When not given, then the default naming strategy will apply.	`string`	`None`
`workspace`	The working directory for any IO operations in this object. If not set, then derive from its parent `workspace`.	`string`	`None`
`log_config`	The YAML config of the logger used in this object.	`string`	`default`
`quiet`	If set, then no log will be emitted from this object.	`boolean`	`False`
`quiet_error`	If set, then exception stack information will not be added to the log	`boolean`	`False`
`timeout_ctrl`	The timeout in milliseconds of the control request, -1 for waiting forever	`number`	`60`
`polling`	The polling strategy of the Deployment and its endpoints (when `shards>1`). Can be defined for all endpoints of a Deployment or by endpoint. Define per Deployment: - ANY: only one (whoever is idle) Pod polls the message - ALL: all Pods poll the message (like a broadcast) Define per Endpoint: JSON dict, {endpoint: PollingType} {‘/custom’: ‘ALL’, ‘/search’: ‘ANY’, ‘*’: ‘ANY’}	`string`	`ANY`
`shards`	The number of shards in the deployment running at the same time. For more details check https://docs.jina.ai/concepts/flow/create-flow/#complex-flow-topologies	`number`	`1`
`replicas`	The number of replicas in the deployment	`number`	`1`
`native`	If set, only native Executors is allowed, and the Executor is always run inside WorkerRuntime.	`boolean`	`False`
`uses`	The config of the executor, it could be one of the followings: * the string literal of an Executor class name * an Executor YAML file (.yml, .yaml, .jaml) * a Jina Hub Executor (must start with `jinahub://` or `jinahub+docker://`) * a docker image (must start with `docker://`) * the string literal of a YAML config (must start with `!` or `jtype:` ) * the string literal of a JSON config When use it under Python, one can use the following values additionally: - a Python dict that represents the config - a text file stream has `.read()` interface	`string`	`BaseExecutor`
`uses_with`	Dictionary of keyword arguments that will override the `with` configuration in `uses`	`object`	`None`
`uses_metas`	Dictionary of keyword arguments that will override the `metas` configuration in `uses`	`object`	`None`
`uses_requests`	Dictionary of keyword arguments that will override the `requests` configuration in `uses`	`object`	`None`
`uses_dynamic_batching`	Dictionary of keyword arguments that will override the `dynamic_batching` configuration in `uses`	`object`	`None`
`py_modules`	The customized python modules need to be imported before loading the executor Note that the recommended way is to only import a single module - a simple python file, if your executor can be defined in a single file, or an `__init__.py` file if you have multiple files, which should be structured as a python package. For more details, please see the `Executor cookbook <https://docs.jina.ai/concepts/executor/executor-files/>`__	`array`	`None`
`output_array_type`	The type of array `tensor` and `embedding` will be serialized to. Supports the same types as `docarray.to_protobuf(.., ndarray_type=...)`, which can be found `here <https://docarray.jina.ai/fundamentals/document/serialization/#from-to-protobuf>`. Defaults to retaining whatever type is returned by the Executor.	`string`	`None`
`exit_on_exceptions`	List of exceptions that will cause the Executor to shut down.	`array`	`[]`
`no_reduce`	Disable the built-in reduction mechanism. Set this if the reduction is to be handled by the Executor itself by operating on a `docs_matrix` or `docs_map`	`boolean`	`False`
`grpc_server_options`	Dictionary of kwargs arguments that will be passed to the grpc server as options when starting the server, example : {‘grpc.max_send_message_length’: -1}	`object`	`None`
`entrypoint`	The entrypoint command overrides the ENTRYPOINT in Docker image. when not set then the Docker image ENTRYPOINT takes effective.	`string`	`None`
`docker_kwargs`	Dictionary of kwargs arguments that will be passed to Docker SDK when starting the docker ‘ container. More details can be found in the Docker SDK docs: https://docker-py.readthedocs.io/en/stable/	`object`	`None`
`volumes`	The path on the host to be mounted inside the container. Note, - If separated by `:`, then the first part will be considered as the local host path and the second part is the path in the container system. - If no split provided, then the basename of that directory will be mounted into container’s root path, e.g. `--volumes="/user/test/my-workspace"` will be mounted into `/my-workspace` inside the container. - All volumes are mounted with read-write mode.	`array`	`None`
`gpus`	This argument allows dockerized Jina Executors to discover local gpu devices. Note, - To access all gpus, use `--gpus all`. - To access multiple gpus, e.g. make use of 2 gpus, use `--gpus 2`. - To access specified gpus based on device id, use `--gpus device=[YOUR-GPU-DEVICE-ID]` - To access specified gpus based on multiple device id, use `--gpus device=[YOUR-GPU-DEVICE-ID1],device=[YOUR-GPU-DEVICE-ID2]` - To specify more parameters, use `–gpus device=[YOUR-GPU-DEVICE-ID],runtime=nvidia,capabilities=display	`string`	`None`
`disable_auto_volume`	Do not automatically mount a volume for dockerized Executors.	`boolean`	`False`
`host`	The host of the Gateway, which the client should connect to, by default it is 0.0.0.0. In the case of an external Executor (`--external` or `external=True`) this can be a list of hosts. Then, every resulting address will be considered as one replica of the Executor.	`array`	`['0.0.0.0']`
`runtime_cls`	The runtime class to run inside the Pod	`string`	`WorkerRuntime`
`timeout_ready`	The timeout in milliseconds of a Pod waits for the runtime to be ready, -1 for waiting forever	`number`	`600000`
`env`	The map of environment variables that are available inside runtime	`object`	`None`
`env_from_secret`	The map of environment variables that are read from kubernetes cluster secrets	`object`	`None`
`floating`	If set, the current Pod/Deployment can not be further chained, and the next `.add()` will chain after the last Pod/Deployment not this current one.	`boolean`	`False`
`reload`	If set, the Executor will restart while serving if YAML configuration source or Executor modules are changed. If YAML configuration is changed, the whole deployment is reloaded and new processes will be restarted. If only Python modules of the Executor have changed, they will be reloaded to the interpreter without restarting process.	`boolean`	`False`
`install_requirements`	If set, try to install `requirements.txt` from the local Executor if exists in the Executor folder. If using Hub, install `requirements.txt` in the Hub Executor bundle to local.	`boolean`	`False`
`port`	The port for input data to bind to, default is a random port between [49152, 65535]. In the case of an external Executor (`--external` or `external=True`) this can be a list of ports. Then, every resulting address will be considered as one replica of the Executor.	`number`	`random in [49152, 65535]`
`monitoring`	If set, spawn an http server with a prometheus endpoint to expose metrics	`boolean`	`False`
`port_monitoring`	The port on which the prometheus server is exposed, default is a random port between [49152, 65535]	`number`	`random in [49152, 65535]`
`retries`	Number of retries per gRPC call. If <0 it defaults to max(3, num_replicas)	`number`	`-1`
`tracing`	If set, the sdk implementation of the OpenTelemetry tracer will be available and will be enabled for automatic tracing of requests and customer span creation. Otherwise a no-op implementation will be provided.	`boolean`	`False`
`traces_exporter_host`	If tracing is enabled, this hostname will be used to configure the trace exporter agent.	`string`	`None`
`traces_exporter_port`	If tracing is enabled, this port will be used to configure the trace exporter agent.	`number`	`None`
`metrics`	If set, the sdk implementation of the OpenTelemetry metrics will be available for default monitoring and custom measurements. Otherwise a no-op implementation will be provided.	`boolean`	`False`
`metrics_exporter_host`	If tracing is enabled, this hostname will be used to configure the metrics exporter agent.	`string`	`None`
`metrics_exporter_port`	If tracing is enabled, this port will be used to configure the metrics exporter agent.	`number`	`None`
`force_update`	If set, always pull the latest Hub Executor bundle even it exists on local	`boolean`	`False`
`prefer_platform`	The preferred target Docker platform. (e.g. “linux/amd64”, “linux/arm64”)	`string`	`None`
`compression`	The compression mechanism used when sending requests from the Head to the WorkerRuntimes. For more details, check https://grpc.github.io/grpc/python/grpc.html#compression.	`string`	`None`
`uses_before_address`	The address of the uses-before runtime	`string`	`None`
`uses_after_address`	The address of the uses-before runtime	`string`	`None`
`connection_list`	dictionary JSON with a list of connections to configure	`string`	`None`
`timeout_send`	The timeout in milliseconds used when sending data requests to Executors, -1 means no timeout, disabled by default	`number`	`None`

Variables#

Jina Flow YAML supports variables and variable substitution according to the Github Actions syntax:

Environment variables#

Use ${{ ENV.VAR }} to refer to the environment variable VAR. You can find all Jina environment variables here.

Context variables#

Use ${{ CONTEXT.VAR }} to refer to the context variable VAR. Context variables can be passed to f.load_config(..., context=...) in the form of a Python dictionary.

Relative paths#

Use ${{root.path.to.var}} to refer to the variable var within the same YAML file, found at the provided path in the file’s structure. Note that the only difference between environment variable syntax and relative path syntax is the omission of spaces in the latter.