SQuARE Datastore API (0.1.0)

Download OpenAPI specification:Download

Knowledge Graphs

Get all knowledge graphs

Get all knowledge graphs from the datastore API

Authorizations:

Auth

Responses

Response samples

200

Content type

application/json

[{"name": "wiki",
"fields": [{"name": "title",
"type": "text"
},
{"name": "text",
"type": "text"
}
]
}
]

Get a knowledge graph

Get a knowledge graph by its name from the datastore API

Authorizations:

Auth

path Parameters

kg_name

required

string (Kg Name)

The knowledge graph name

Responses

Response samples

200
422

Content type

application/json

{"name": "wiki",
"fields": [{"name": "title",
"type": "text"
},
{"name": "text",
"type": "text"
}
]
}

Create a knowledge graph

Create a new knowledge graph

Authorizations:

Auth

path Parameters

kg_name

required

string (Kg Name)

The knowledge graph name

Responses

Response samples

200
422

Content type

application/json

null

Delete a knowledge graph

Delete a knowledge graph from the datastore API

Authorizations:

Auth

path Parameters

kg_name

required

string (Kg Name)

The knowledge graph name

Responses

Response samples

200
422

Content type

application/json

null

Get knowledge graph statistics

Get statistics such as document count and storage size in bytes for a knowledge graph.

Authorizations:

Auth

path Parameters

kg_name

required

string (Kg Name)

The knowledge graph name

Responses

Response samples

200
422

Content type

application/json

{"name": "test",
"documents": 10,
"size_in_bytes": 1280
}

Get all knowledge graph relations

Get all relations of a given knowledge graph.

Authorizations:

Auth

path Parameters

kg_name

required

string (Kg Name)

The knowledge graph name

Responses

Response samples

200
422

Content type

application/json

null

Insert/Update a node.

Inserts/Updates a node with its ID as .

Authorizations:

Auth

path Parameters

kg_name required	string (Kg Name) The knowledge graph name
node_id required	string (Node Id) The node name

Request Body schema: application/json

object (Node)

The node to upsert

Responses

Request samples

Payload

Content type

application/json

{"id": "1",
"title": "The document title.",
"text": "Some text of the document."
}

Response samples

200
422

Content type

application/json

null

Upload a batch of nodes

Authorizations:

Auth

path Parameters

kg_name

required

string (Kg Name)

The name of the knowledge graph

Request Body schema: application/json

Array

object (Document)

A Mapping is a generic container for associating key/value pairs.

This class provides concrete generic implementations of all methods except for getitem, iter, and len.

Responses

Request samples

Payload

Content type

application/json

[{"id": "1",
"title": "The document title.",
"text": "Some text of the document."
}
]

Response samples

201
400
404

Content type

application/json

{"message": "string",
"successful_uploads": 0,
"errors": 0
}

Get a node from a knowledge graph

Get a node from the knowledge graph by name

Authorizations:

Auth

path Parameters

kg_name

required

string (Kg Name)

The name of the node

Request Body schema: application/json

Array

any

Responses

Request samples

Payload

Content type

application/json

[null
]

Response samples

200
422

Content type

application/json

null

Get a list of nodes which are between a pair of nodes.

Returns a list of nodes, which are inbetween a list of node-pairs..

Authorizations:

Auth

path Parameters

kg_name

required

string (Kg Name)

The name of the edge

Request Body schema: application/json

Array

any

Responses

Request samples

Payload

Content type

application/json

[null
]

Response samples

200
422
500

Content type

application/json

null

summary

Get the subgraph of a given List of node-names and the number of hops

Authorizations:

Auth

path Parameters

kg_name

required

string (Kg Name)

The knowledge graph name

Request Body schema: application/json

nids required	Array of any (Nids) unique List of node names.
hops	integer (Hops) Default: 2 Number of hops to retrieve.

Responses

Request samples

Payload

Content type

application/json

{"nids": [null
],
"hops": 2
}

Response samples

200
422

Content type

application/json

null

summary

Get the subgraph of a given List of node-ids and the number of hops

Authorizations:

Auth

path Parameters

kg_name

required

string (Kg Name)

The knowledge graph name

Request Body schema: application/json

nids required	Array of any (Nids) unique List of node ids.
hops	integer (Hops) Default: 2 Number of hops to retrieve.

Responses

Request samples

Payload

Content type

application/json

{"nids": [null
],
"hops": 2
}

Response samples

200
422

Content type

application/json

null

Get edges between given node_ids

Get edges between node_pairs for a given list of node_id_pairs from the knowledge.

Authorizations:

Auth

path Parameters

kg_name

required

string (Kg Name)

The name of the knowledge graph

Request Body schema: application/json

Array

any

Responses

Request samples

Payload

Content type

application/json

[[null
]
]

Response samples

200
422
500

Content type

application/json

null

Get the relation info between given node_ids

Get relation info between node_pairs for a given list of node_id_pairs from the knowledge.

Authorizations:

Auth

path Parameters

kg_name

required

string (Kg Name)

The name of the knowledge graph

Request Body schema: application/json

Array

any

Responses

Request samples

Payload

Content type

application/json

[[null
]
]

Response samples

200
422
500

Content type

application/json

null

Get a edge from a knowledge graph

Get a edge from the knowledge graph by name

Authorizations:

Auth

path Parameters

kg_name

required

string (Kg Name)

The name of the knowledge graph

Request Body schema: application/json

Array

any

Responses

Request samples

Payload

Content type

application/json

[null
]

Response samples

200
422
500

Content type

application/json

null

Get list of nodes which go in or out of given node for given knowledge graph

Returns a list of nodes, which either go in or out of the given node.

Authorizations:

Auth

path Parameters

kg_name

required

string (Kg Name)

The name of the edge

Request Body schema: application/json

Array

any

Responses

Request samples

Payload

Content type

application/json

[null
]

Response samples

200
422
500

Content type

application/json

null

Get a node/edge from a knowledge graph

Get a node/edge from the knowledge graph by its ID.

Authorizations:

Auth

path Parameters

kg_name required	string (Kg Name) The name of the knowdledge graph
object_id required	string (Object Id) The name of the node/edge to retrieve

Responses

Response samples

200
400
422

Content type

application/json

{"id": "1",
"title": "The document title.",
"text": "Some text of the document."
}

Delete a node/edge from knwoledge graph

Delete a node/edge from the datastore API by its ID.

Authorizations:

Auth

path Parameters

kg_name required	string (Kg Name) The knowledge graph name
object_id required	string (Object Id) The node/edge ID

Responses

Response samples

200
422

Content type

application/json

null

Datastores

Get all datastores

Get all datastores from the datastore API

Authorizations:

Auth

Responses

Response samples

200

Content type

application/json

[{"name": "wiki",
"fields": [{"name": "title",
"type": "text"
},
{"name": "text",
"type": "text"
}
]
}
]

Get a datastore

Get a datastore by its name from the datastore API

Authorizations:

Auth

path Parameters

datastore_name

required

string (Datastore Name)

The datastore name

Responses

Response samples

200
422

Content type

application/json

{"name": "wiki",
"fields": [{"name": "title",
"type": "text"
},
{"name": "text",
"type": "text"
}
]
}

Create a datastore

Create a new datastore

Authorizations:

Auth

path Parameters

datastore_name

required

string (Datastore Name)

The datastore name

Request Body schema: application/json

Array

name required	string (Name)
type required	string (Type)

Responses

Request samples

Payload

Content type

application/json

[{"name": "title",
"type": "text"
},
{"name": "text",
"type": "text"
}
]

Response samples

200
422

Content type

application/json

{"name": "wiki",
"fields": [{"name": "title",
"type": "text"
},
{"name": "text",
"type": "text"
}
]
}

Delete a datastore

Delete a datastore from the datastore API

Authorizations:

Auth

path Parameters

datastore_name

required

string (Datastore Name)

The datastore name

Responses

Response samples

200
422

Content type

application/json

null

Get datastore statistics

Get statistics such as document count and storage size in bytes for a datastore.

Authorizations:

Auth

path Parameters

datastore_name

required

string (Datastore Name)

The datastore name

Responses

Response samples

200
422

Content type

application/json

{"name": "test",
"documents": 10,
"size_in_bytes": 1280
}

Documents

Upload documents from a file to the datastore

Upload all documents from a jsonl file to the datastore

Authorizations:

Auth

path Parameters

datastore_name

required

string (Datastore Name)

The name of the datastore

Request Body schema: multipart/form-data

file

required

string <binary> (File)

The file containing the documents to upload

Responses

Response samples

201
400
404
422

Content type

application/json

{"message": "string",
"successful_uploads": 0,
"errors": 0
}

Upload documents from a file at the given url to the datastore

Authorizations:

Auth

path Parameters

datastore_name

required

string (Datastore Name)

The name of the datastore

Request Body schema: application/json

urls

required

Array of strings (Urls)

Responses

Request samples

Payload

Content type

application/json

{"urls": ["http://localhost:3000/documents/0.jsonl"
]
}

Response samples

201
400
404
422

Content type

application/json

{"message": "string",
"successful_uploads": 0,
"errors": 0
}

Get all documents from the datastore

Lists all documents from the datastore

Authorizations:

Auth

path Parameters

datastore_name

required

string (Datastore Name)

The name of the datastore

Responses

Response samples

400
422

Content type

application/json

{"detail": "string"
}

Upload a batch of documents

Authorizations:

Auth

path Parameters

datastore_name

required

string (Datastore Name)

The name of the datastore

Request Body schema: application/json

Array

object (Document)

A Mapping is a generic container for associating key/value pairs.

This class provides concrete generic implementations of all methods except for getitem, iter, and len.

Responses

Request samples

Payload

Content type

application/json

[{"id": "1",
"title": "The document title.",
"text": "Some text of the document."
}
]

Response samples

201
400
404

Content type

application/json

{"message": "string",
"successful_uploads": 0,
"errors": 0
}

Get a document from the datastore

Get a document from the datastore by id

Authorizations:

Auth

path Parameters

datastore_name required	string (Datastore Name) The name of the datastore
doc_id required	string (Doc Id) The id of the document to retrieve

Responses

Response samples

200
400
422

Content type

application/json

{"id": "1",
"title": "The document title.",
"text": "Some text of the document."
}

Update a document in the datastore

Update a document in the datastore by id

Authorizations:

Auth

path Parameters

datastore_name required	string (Datastore Name) The name of the datastore
doc_id required	string (Doc Id) The id of the document to update

Request Body schema: application/json

object (Document)

The document to update

Responses

Request samples

Payload

Content type

application/json

{"id": "1",
"title": "The document title.",
"text": "Some text of the document."
}

Response samples

200
400

Content type

application/json

null

Delete a document from the datastore

Delete a document from the datastore by id

Authorizations:

Auth

path Parameters

datastore_name required	string (Datastore Name) The name of the datastore
doc_id required	string (Doc Id) The id of the document to delete

Responses

Response samples

200
422

Content type

application/json

null

Query

Search the documentstore with given query and return top-k documents

Searches the given datastore with the search strategy specified by the given index and if necessery encodes the query with the specified encoder

Authorizations:

Auth

path Parameters

datastore_name

required

string (Datastore Name)

Name of the datastore.

query Parameters

index_name	string (Index Name) Index name.
query required	string (Query) The query string.
top_k	integer (Top K) Default: 40 Number of documents to retrieve.
feedback_documents	Array of strings (Feedback Documents) Relevant feedback documents from previous query.
region	any (Region) Enum: "da-DK" "de-AT" "de-CH" "de-DE" "en-AU" "en-CA" "en-GB" "en-ID" "en-IN" "en-MY" "en-NZ" "en-PH" "en-US" "en-ZA" "es-AR" "es-CL" "es-ES" "es-MX" "es-US" "fi-FI" "fr-BE" "fr-CA" "fr-CH" "fr-FR" "it-IT" "ja-JP" "ko-KR" "nl-BE" "nl-NL" "no-NO" "pl-PL" "pt-BR" "ru-RU" "sv-SE" "tr-TR" "zh-CN" "zh-HK" "zh-TW" Region of the query when using the bing_search datastore.

Responses

Response samples

200
404
422
500

Content type

application/json

[{"document": {"id": "1",
"title": "The document title.",
"text": "Some text of the document."
},
"score": 0,
"id": "string"
}
]

Search a datastore with the given query vector and return top-k documents

Searches the given datastore with the search strategy specified by the given index

Authorizations:

Auth

path Parameters

datastore_name

required

string (Datastore Name)

Name of the datastore.

Request Body schema: application/json

index_name required	string (Index Name) Index name.
query_vector required	Array of numbers (Query Vector) Query vector.
top_k	integer (Top K) Default: 40 Number of documents to retrieve.

Responses

Request samples

Payload

Content type

application/json

{"index_name": "string",
"query_vector": [0
],
"top_k": 40
}

Response samples

200
404
422
500

Content type

application/json

[{"document": {"id": "1",
"title": "The document title.",
"text": "Some text of the document."
},
"score": 0,
"id": "string"
}
]

Score the document with given query

Scores the document with the given id and the given query and returns the score.

Authorizations:

Auth

path Parameters

datastore_name

required

string (Datastore Name)

Name of the datastore.

query Parameters

index_name	string (Index Name) Index name.
query required	string (Query) The query string.
doc_id required	string (Doc Id) Document ID to retrieve.

Responses

Response samples

200
404
422
500

Content type

application/json

{"document": {"id": "1",
"title": "The document title.",
"text": "Some text of the document."
},
"score": 0,
"id": "string"
}

Indices

Lists all indices of a datastore

Returns a list of all indices in a datastore.

Authorizations:

Auth

path Parameters

datastore_name

required

string (Datastore Name)

Datastore name

Responses

Response samples

200
422

Content type

application/json

[{"datastore_name": "wiki",
"name": "dpr",
"doc_encoder_model": "facebook/dpr-ctx_encoder-single-nq-base",
"query_encoder_model": "facebook/dpr-question_encoder-single-nq-base",
"embedding_size": 768,
"embedding_mode": "pooler",
"index_url": "https://public.ukp.informatik.tu-darmstadt.de/kwang/faiss-instant/dpr-single-nq-base.size-full/nq-QT_8bit_uniform-ivf262144.index",
"index_ids_url": "https://public.ukp.informatik.tu-darmstadt.de/kwang/faiss-instant/dpr-single-nq-base.size-full/nq-QT_8bit_uniform-ivf262144.txt",
"index_description": "It uses Faiss-IVF-SQ with nlist = 2^18, nprobe = 512 and 8bit uniform. For the indexing script, please refer to https://gist.github.com/kwang2049/d23550604059ed1576ac6cffb7e09fb2",
"collection_url": "https://dl.fbaipublicfiles.com/dpr/wikipedia_split/psgs_w100.tsv.gz"
}
]

Get an index by its name

Returns an index for a datastore given its name.

Authorizations:

Auth

path Parameters

datastore_name required	string (Datastore Name) Name of the datastore
index_name required	string (Index Name) Name of the index

Responses

Response samples

200
404
422

Content type

application/json

{"datastore_name": "wiki",
"name": "dpr",
"doc_encoder_model": "facebook/dpr-ctx_encoder-single-nq-base",
"query_encoder_model": "facebook/dpr-question_encoder-single-nq-base",
"embedding_size": 768,
"embedding_mode": "pooler",
"index_url": "https://public.ukp.informatik.tu-darmstadt.de/kwang/faiss-instant/dpr-single-nq-base.size-full/nq-QT_8bit_uniform-ivf262144.index",
"index_ids_url": "https://public.ukp.informatik.tu-darmstadt.de/kwang/faiss-instant/dpr-single-nq-base.size-full/nq-QT_8bit_uniform-ivf262144.txt",
"index_description": "It uses Faiss-IVF-SQ with nlist = 2^18, nprobe = 512 and 8bit uniform. For the indexing script, please refer to https://gist.github.com/kwang2049/d23550604059ed1576ac6cffb7e09fb2",
"collection_url": "https://dl.fbaipublicfiles.com/dpr/wikipedia_split/psgs_w100.tsv.gz"
}

Creates a new index or updates it if it exists

Creates a new index in the specified datastore of a index with that name allready exists it is updated to the given configuration

Authorizations:

Auth

path Parameters

datastore_name required	string (Datastore Name) Name of the datastore
index_name required	string (Index Name) Name of the index

Request Body schema: application/json

doc_encoder_model	string (Doc Encoder Model)
doc_encoder_adapter	string (Doc Encoder Adapter)
query_encoder_model	string (Query Encoder Model)
query_encoder_adapter	string (Query Encoder Adapter)
embedding_size	integer (Embedding Size)
embedding_mode	string (Embedding Mode)
index_url	string (Index Url)
index_ids_url	string (Index Ids Url)
index_description	string (Index Description)
collection_url	string (Collection Url)

Responses

Request samples

Payload

Content type

application/json

{"doc_encoder_model": "facebook/dpr-ctx_encoder-single-nq-base",
"query_encoder_model": "facebook/dpr-question_encoder-single-nq-base",
"embedding_size": 768,
"embedding_mode": "pooler",
"index_url": "https://public.ukp.informatik.tu-darmstadt.de/kwang/faiss-instant/dpr-single-nq-base.size-full/nq-QT_8bit_uniform-ivf262144.index",
"index_ids_url": "https://public.ukp.informatik.tu-darmstadt.de/kwang/faiss-instant/dpr-single-nq-base.size-full/nq-QT_8bit_uniform-ivf262144.txt",
"index_description": "It uses Faiss-IVF-SQ with nlist = 2^18, nprobe = 512 and 8bit uniform. For the indexing script, please refer to https://gist.github.com/kwang2049/d23550604059ed1576ac6cffb7e09fb2",
"collection_url": "https://dl.fbaipublicfiles.com/dpr/wikipedia_split/psgs_w100.tsv.gz"
}

Response samples

200
201
400
422
500

Content type

application/json

{"datastore_name": "wiki",
"name": "dpr",
"doc_encoder_model": "facebook/dpr-ctx_encoder-single-nq-base",
"query_encoder_model": "facebook/dpr-question_encoder-single-nq-base",
"embedding_size": 768,
"embedding_mode": "pooler",
"index_url": "https://public.ukp.informatik.tu-darmstadt.de/kwang/faiss-instant/dpr-single-nq-base.size-full/nq-QT_8bit_uniform-ivf262144.index",
"index_ids_url": "https://public.ukp.informatik.tu-darmstadt.de/kwang/faiss-instant/dpr-single-nq-base.size-full/nq-QT_8bit_uniform-ivf262144.txt",
"index_description": "It uses Faiss-IVF-SQ with nlist = 2^18, nprobe = 512 and 8bit uniform. For the indexing script, please refer to https://gist.github.com/kwang2049/d23550604059ed1576ac6cffb7e09fb2",
"collection_url": "https://dl.fbaipublicfiles.com/dpr/wikipedia_split/psgs_w100.tsv.gz"
}

Delete an index

Deletes the index with the corresponding name and all embeddings contained in the index

Authorizations:

Auth

path Parameters

datastore_name required	string (Datastore Name) The name of the datastore
index_name required	string (Index Name) The name of the index

Responses

Response samples

200
404
422
500

Content type

application/json

null

Gets the status of an index

Returns whether an index is currently available for search.

Authorizations:

Auth

path Parameters

datastore_name required	string (Datastore Name) Name of the datastore
index_name required	string (Index Name) Name of the index

Responses

Response samples

200
404
422

Content type

application/json

{"is_available": true
}

Get embedding for a document

Returns the embedding for a document in the indexwith the given id

Authorizations:

Auth

path Parameters

datastore_name required	string (Datastore Name) The name of the datastore
index_name required	string (Index Name) The name of the index
doc_id required	string (Doc Id) The id of the document

Responses

Response samples

200
404
422

Content type

application/json

{"id": "1",
"embedding": [0.1,
0.2,
0.3,
0.4,
0.5,
0.6,
0.7,
0.8,
0.9
]
}