Preliminaries#

This chapter introduces the basic terminology you will encounter in the docs. But first, look at the code below:

from jina import DocumentArray, Executor, Flow, requests


class FooExec(Executor):
    @requests
    async def add_text(self, docs: DocumentArray, **kwargs):
        for d in docs:
            d.text += 'hello, world!'


class BarExec(Executor):
    @requests
    async def add_text(self, docs: DocumentArray, **kwargs):
        for d in docs:
            d.text += 'goodbye!'


f = Flow(port=12345).add(uses=FooExec, replicas=3).add(uses=BarExec, replicas=2)

with f:
    f.block()
from jina import Client, DocumentArray

c = Client(port=12345)
r = c.post('/', DocumentArray.empty(2))
print(r.texts)

Running it gives you:

['hello, world!goodbye!', 'hello, world!goodbye!']

This animation shows what’s happening behind the scenes:

../../_images/arch-overview.svg

The following concepts are covered in the user guide:

Document#

Document is the fundamental data structure in Jina for representing multimodal data. It is the essential element of IO in Jina. More information can be found in DocArray’s Docs.

DocumentArray#

DocumentArray is a list-like container of multiple Documents. More information can be found in DocArray’s Docs.

Executor#

Executor is a Python class that has a group of functions using DocumentArray as IO. Loosely speaking, each Executor is a microservice.

Flow#

Flow ties multiple Executors together into a logic pipeline to achieve a task. If an Executor is a microservice, then a Flow is the end-to-end service.

Gateway#

Gateway is the entrypoint of a Flow. It exposes multiple protocols for external communications; it routes all internal traffic.

Client#

Client connects to a Gateway and sends/receives data from it.

Deployment#

Deployment is an abstraction around Executor that lets the Gateway communicate with an Executor. It encapsulates and abstracts internal replication details.

gRPC, WebSocket, HTTP#

These are network protocols for transmitting data. gRPC is always used for communication between Gateway and Deployment.

TLS#

TLS is a security protocol to facilitate privacy and data security for communications over the Internet. The communication between Client and Gateway is protected by TLS.