Preliminaries#

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

Server

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()

Client

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:

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.