Protocol Documentation

Table of Contents

• jina.proto

  • DenseNdArrayProto

  • DocumentArrayProto

  • DocumentProto

  • DocumentProto.EvaluationsEntry

  • DocumentProto.ScoresEntry

  • EnvelopeProto

  • EnvelopeProto.CompressConfigProto

  • EnvelopeProto.VersionProto

  • GraphProto

  • HeaderProto

  • MessageProto

  • NamedScoreProto

  • NdArrayProto

  • RequestProto

  • RequestProto.ControlRequestProto

  • RequestProto.DataRequestProto

  • RouteProto

  • RoutingEdgeProto

  • RoutingTableProto

  • RoutingTableProto.PodsEntry

  • SparseNdArrayProto

  • StatusProto

  • StatusProto.ExceptionProto

  • TargetPodProto

  • DenseNdArrayProto.QuantizationMode

  • RequestProto.ControlRequestProto.Command

  • StatusProto.StatusCode

  • JinaRPC

• Scalar Value Types

Top

jina.proto

DenseNdArrayProto

Represents a (quantized) dense n-dim array

Field	Type	Label	Description
buffer	bytes		the actual array data, in bytes
shape	uint32	repeated	the shape (dimensions) of the array
dtype	string		the data type of the array
quantization	DenseNdArrayProto.QuantizationMode		quantization mode
max_val	float		the max value of the ndarray
min_val	float		the min value of the ndarray
scale	float		the scale of the ndarray
original_dtype	string		the original dtype of the array

DocumentArrayProto

Field	Type	Label	Description
docs	DocumentProto	repeated	a list of Documents

DocumentProto

Represents a Document

Field	Type	Label	Description
id	string		A hexdigest that represents a unique document ID
granularity	uint32		the depth of the recursive chunk structure
adjacency	uint32		the width of the recursive match structure
parent_id	string		the parent id from the previous granularity
buffer	bytes		the raw binary content of this document, which often represents the original document when comes into jina
blob	NdArrayProto		the ndarray of the image/audio/video document
text	string		a text document
uri	string		a uri of the document could be: a local file path, a remote url starts with http or https or data URI scheme
graph	GraphProto		Related information to be used when a Document represents a graph with its chunks as nodes
chunks	DocumentProto	repeated	list of the sub-documents of this document (recursive structure)
weight	float		The weight of this document
matches	DocumentProto	repeated	the matched documents on the same level (recursive structure)
mime_type	string		mime type of this document, for buffer content, this is required; for other contents, this can be guessed
tags	google.protobuf.Struct		a structured data value, consisting of field which map to dynamically typed values.
location	uint32	repeated	the position of the doc, could be start and end index of a string; could be x,y (top, left) coordinate of an image crop; could be timestamp of an audio clip
offset	uint32		the offset of this doc in the previous granularity document
embedding	NdArrayProto		the embedding ndarray of this document
scores	DocumentProto.ScoresEntry	repeated	Scores performed on the document, each element corresponds to a metric
modality	string		modality, an identifier to the modality this document belongs to. In the scope of multi/cross modal search
evaluations	DocumentProto.EvaluationsEntry	repeated	Evaluations performed on the document, each element corresponds to a metric

DocumentProto.EvaluationsEntry

Field	Type	Label	Description
key	string
value	NamedScoreProto

DocumentProto.ScoresEntry

Field	Type	Label	Description
key	string
value	NamedScoreProto

EnvelopeProto

Represents a Envelope, a part of the Message.

Field	Type	Label	Description
sender_id	string		unique id of the sender of the message
receiver_id	string		unique id of the receiver of the message, only used in router-dealer pattern
request_id	string		unique id of the request
timeout	uint32		timeout in second until this message is dropped
version	EnvelopeProto.VersionProto		version info
request_type	string		type of the request: DataRequest, ControlRequest
check_version	bool		check local Protobuf version on every Pod that this message flows to
compression	EnvelopeProto.CompressConfigProto		compress configuration used for request
routes	RouteProto	repeated	status info on every routes
routing_table	RoutingTableProto		the routing table contains information to the next pods
status	StatusProto		status info
header	HeaderProto		header contains meta info defined by the user, copied from Request, for lazy serialization

EnvelopeProto.CompressConfigProto

Represents a config for the compression algorithm

Field	Type	Label	Description
algorithm	string		compress algorithm used for request
min_bytes	uint64		the high watermark that triggers the message compression. message bigger than this HWM (in bytes) will be compressed by the algorithm.
min_ratio	float		the low watermark that enables the sending of a compressed message. compression rate (after_size/before_size) lower than this LWM will be considered as successeful compression, and will be sent. Otherwise, it will send the original message without compression
parameters	google.protobuf.Struct		other parameters that can be accepted by the algorithm

EnvelopeProto.VersionProto

Represents a the version information

Field	Type	Label	Description
jina	string		jina's version
proto	string		protobuf's version
vcs	string		vcs's version

GraphProto

Represents a Graph

Field	Type	Label	Description
adjacency	SparseNdArrayProto		adjacency list
edge_features	google.protobuf.Struct		Container structure to store edge features
undirected	bool		Flag indicating if the graph is to be interpreted as an undirected graph

HeaderProto

Represents a Header.

• The header’s content will be defined by the user request.

• It will be copied to the envelope.header

• In-flow operations will modify the envelope.header

• While returning, copy envelope.header back to request.header

Field	Type	Label	Description
exec_endpoint	string		the endpoint specified by @requests(on='/abc')
target_peapod	string		if set, the request is targeted to certain peas/pods, regex strings
no_propagate	bool		if set, then this request is not propagate over the Flow topology

MessageProto

Represents a Message

Field	Type	Label	Description
envelope	EnvelopeProto		the envelope of the message, used internally in jina, dropped when returning to client
request	RequestProto		the request body

NamedScoreProto

Represents the relevance model to ref_id

Field	Type	Label	Description
value	float		value
op_name	string		the name of the operator/score function
description	string		text description of the score
operands	NamedScoreProto	repeated	the score can be nested
ref_id	string		the score is computed between doc id and ref_id

NdArrayProto

Represents a general n-dim array, can be either dense or sparse

Field	Type	Label	Description
dense	DenseNdArrayProto		dense representation of the ndarray
sparse	SparseNdArrayProto		sparse representation of the ndarray

RequestProto

Represents a Request

Field	Type	Label	Description
request_id	string		the unique ID of this request. Multiple requests with the same ID will be gathered
control	RequestProto.ControlRequestProto		a control request
data	RequestProto.DataRequestProto		a data request
header	HeaderProto		header contains meta info defined by the user
parameters	google.protobuf.Struct		extra kwargs that will be used in executor
routes	RouteProto	repeated	status info on every routes
status	StatusProto		status info

RequestProto.ControlRequestProto

Represents a control request used to control the BasePod

Field	Type	Label	Description
command	RequestProto.ControlRequestProto.Command		the control command

RequestProto.DataRequestProto

Represents a general data request

Field	Type	Label	Description
docs	DocumentProto	repeated	a list of Documents to query
groundtruths	DocumentProto	repeated	a list of groundtruth Document you want to evaluate it with

RouteProto

Represents a the route paths of this message

Field	Type	Label	Description
pod	string		the name of the BasePod
pod_id	string		the id of the BasePod
start_time	google.protobuf.Timestamp		receiving time
end_time	google.protobuf.Timestamp		sending (out) time
status	StatusProto		the status of the execution

RoutingEdgeProto

Field	Type	Label	Description
pod	string
send_as_bind	bool

RoutingTableProto

Field	Type	Label	Description
pods	RoutingTableProto.PodsEntry	repeated	Pods that get visited during a Flow. Gateway should be both the first and the last entry.
active_pod	string		The currently active Pod. Needed for ZMQ.

RoutingTableProto.PodsEntry

Field	Type	Label	Description
key	string
value	TargetPodProto

SparseNdArrayProto

Represents a sparse ndarray

Field	Type	Label	Description
indices	DenseNdArrayProto		A 2-D int64 tensor of shape [N, ndims], which specifies the indices of the elements in the sparse tensor that contain nonzero values (elements are zero-indexed)
values	DenseNdArrayProto		A 1-D tensor of any type and shape [N], which supplies the values for each element in indices.
shape	uint32	repeated	A 1-D int64 tensor of shape [ndims], which specifies the shape of the sparse tensor.

StatusProto

Represents a Status

Field	Type	Label	Description
code	StatusProto.StatusCode		status code
description	string		error description of the very first exception
exception	StatusProto.ExceptionProto		the details of the error

StatusProto.ExceptionProto

Field	Type	Label	Description
name	string		the class name of the exception
args	string	repeated	the list of arguments given to the exception constructor.
stacks	string	repeated	the exception traceback stacks
executor	string		the name of the executor bind to that peapod (if applicable)

TargetPodProto

Field	Type	Label	Description
host	string		the host HeadPea of the BasePod
port	uint32		the port HeadPea of the BasePod
port_out	uint32		the port TailPea of the BasePod
expected_parts	uint32		the number of parts the pod should expect
out_edges	RoutingEdgeProto	repeated	pod_name of Pods, the TailPea should send traffic to
target_identity	string

DenseNdArrayProto.QuantizationMode

Name	Number	Description
NONE	0	no quantization is performed, stored in the original dtype
FP16	1	2x smaller if dtype is set to FP32
UINT8	2	4x smaller but lossy when dtype is FP32

RequestProto.ControlRequestProto.Command

Name	Number	Description
TERMINATE	0	shutdown the BasePod
STATUS	1	check the status of the BasePod
IDLE	2	used in ROUTER-DEALER pattern, tells the router that the dealer is idle
CANCEL	3	used in ROUTER-DEALER pattern, tells the router that the dealer is busy (or closed)
SCALE	4	scale up/down a Pod
ACTIVATE	5	used in ROUTER-DEALER pattern, Indicate a Pea that it can activate itself and send the IDLE command to their router
DEACTIVATE	6	used in ROUTER-DEALER pattern, Indicate a Pea that it can deactivate itself and send the CANCEL command to their router

StatusProto.StatusCode

Name	Number	Description
SUCCESS	0	success
PENDING	1	there are pending messages, more messages are followed
READY	2	ready to use
ERROR	3	error
ERROR_DUPLICATE	4	already a existing pod running
ERROR_NOTALLOWED	5	not allowed to open pod remotely
ERROR_CHAINED	6	chained from the previous error

JinaRPC

jina gRPC service.

Method Name	Request Type	Response Type	Description
Call	RequestProto stream	RequestProto stream	Pass in a Request and a filled Request with matches will be returned.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)