# Quick Start

To start using Hyperspace, follow these steps:

### 1. Install the Hyperspace API Client

Run the following shell command in your code or your data terminal –

d host address, use the following code to connect to the database through the Hyperspace API.

{% tabs %}
{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
pip install hyperspace-py
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```python
npm install https://github.com/hyper-space-io/hyperspace-js
```

{% endcode %}
{% endtab %}
{% endtabs %}

for more information, see [here](https://docs.hyper-space.io/hyperspace-docs/projects/setting-up/installing-the-hyperspace-api-client).

### **2. Create a local instance of the Hyperspace client** 

Once you receive credentials and host address, use the following code to connect to the database through the Hyperspace API.

{% tabs %}
{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
hyperspace_client = hyperspace.HyperspaceClientApi(host=host_address,
                                                      username=username,
                                                      password=password)
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
import io.hyperspace.client.HyperspaceClient;
HyperspaceClient client = new HyperspaceClient(host, username, password);
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```javascript
const hs = require('hyperspace-js')
const hyperspaceClient = new hs.HyperspaceClient(host, username, password)
```

{% endcode %}
{% endtab %}
{% endtabs %}

### **3. Run Hyperspace queries**

#### **Create a schema file**

The schema files outline the data structure, index and metric types, and similar configurations. More info can be found in the [configuration file](https://docs.hyper-space.io/hyperspace-docs/projects/setting-up/creating-a-database-schema-configuration-file) section. 

#### **Create a collection**

Copy the following code snippet to create a collection

{% tabs %}
{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
collection_name = 'new_collection'
hyperspace_client.create_collection('schema.json', collection_name)
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
JsonObject schema = (JsonObject) 
JsonParser.parseReader(new FileReader("schema.json"));
client.createCollection(collectionName, schema);
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```javascript
const collection_name = 'new_collection'
await hyperspaceClient.createCollection('schema.json', collection_name)
```

{% endcode %}
{% endtab %}
{% endtabs %}

**Where** –

* '<mark style="color:purple;">schema.json</mark>' – Specifies the path to the configuration file that you created locally on your machine.
* <mark style="color:purple;">collection\_name</mark>' – Specifies the name of the collection to be created in the Hyperspace database.&#x20;

Alternatively, you can define the database config schema as a local python object

{% tabs %}
{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
schema = {
        "configuration": {
            "name": {
                "type": "keyword"
            },
            "id": {
                "type": "keyword",
                "id": True,
            }
        }
    }
hyperspace_client.create_collection(schema, 'collection_name')
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
String schema = "{" +
                "  \"configuration\": {" +
                "  \"name\": {" +
                "               \"type\":\"keyword\"" +
                "            }" +
                "  \"id\":   {" +
                "               \"type\":\"keyword\"" +
                "               \"id\":\"true\"" +                
                "            }" +    
                "        }" +
                "      }";
                

hyperspaceClient.createCollection(collectionName, schema);
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```python
const schema = {
    "configuration": {
        "name": {
            "type": "keyword"
        },
        "id": {
            "type": "keyword",
            "id": true,
        }
    }
};

await hyperspaceClient.createCollection(collectionName, schema);
```

{% endcode %}
{% endtab %}
{% endtabs %}

**Where** –

* <mark style="color:purple;">schema</mark> – Specifies the python dictionary that outlines the configuration schema.
* '<mark style="color:purple;">collection\_name</mark>' – Specifies the name of the collection to be created in the Hyperspace database.&#x20;

#### **Upload Data**&#x20;

Data can be uploaded in batches. Copy the following code snippet to upload data

{% tabs %}
{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
batch_size = 250
batch = []

for i, data_point in enumerate(documents):
   batch.append(data_point)
   if (i+1) % batch_size == 0:
      response = hyperspace_client.add_batch(batch, collection_name)
      batch.clear()
      
if batch:
  response = hyperspace_client.add_batch(batch, collection_name)
  
hyperspace_client.commit(collection_name)
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
import java.util.ArrayList;
final int batchSize = 250;

for (int i= 0; index < documents.size(); i++) {
    batch.add(documents.get(i));
    if ((i+ 1) % batchSize == 0) {
          List<DataPoint> batchCopy = new ArrayList<>(batch);
          futures.add(hyperspaceClient.addBatch(batchCopy, collectionName));
          batch.clear();
      }    
}

if (!batch.isEmpty()) {
    futures.add(hyperspaceClient.addBatch(new ArrayList<>(batch), collectionName));
}
CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
hyperspaceClient.commit(collectionName).join();
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```javascript
let BATCH_SIZE = 250;
let batch: any[] = [];
let collectionName = "new_collection";

for (const [i, document] of documents.entries()) {
    batch.push(document);
    if ((i + 1) % BATCH_SIZE == 0) {
        await client.addBatch(collectionName, batch);
        batch = [];
    }
}

if (batch.length != 0) {
    await client.addBatch(collectionName, batch);
}
await client.commit(collectionName)
```

{% endcode %}
{% endtab %}
{% endtabs %}

**Where** –

* <mark style="color:purple;">data\_point</mark> – Represents the document to upload. Each document must have dictionary like structure with a keys according to the database schema configuration file.
* <mark style="color:purple;">batch\_size</mark> – Specifies the number of documents in a batch.
* `commit` is required for vector search only

#### **Build and run a query (Python only)**

Hyperspace queries can be of one of the following types  –

* **Lexical Search**
* **Vector Search**
* **Hybrid Search**&#x20;

Lexical search can be performed in DSL syntax, or as using a [score function](https://docs.hyper-space.io/hyperspace-docs/projects/score-function-commands) of the following form:

{% code lineNumbers="true" %}

```python
 def score_function (params , doc) :
     score = 0.0
     if match ('metadata field 1'):
       score = 1.0
       if match ('metadata field 1'):
          score 2.0
 return score
```

{% endcode %}

#### **To set a hybrid or lexical search query –**

Specify that this score function file is to be used for the Search, as follows –

{% tabs %}
{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
hyperspace_client.set_function(score_function_name,
                                collection_name=collection_name,
                                function_name='score_function')
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```javascript
String function = Files.readString(Paths.get("score_function.py"));
client.setFunction(collectionName, "score_function", function);
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```python
await hyperspaceClient.setFunction(score_function_name,
                                collection_name=collection_name,
                                function_name='score_function')
```

{% endcode %}
{% endtab %}
{% endtabs %}

#### **To run a hybrid or lexical search query  –**

define the query schema and run&#x20;

{% tabs %}
{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
params= {
         "name": "John"
        }
results = hyperspace_client.search(params,
                                   size=10,                 
                                   collection_name=collection_name
                                   function_name='score_function')
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
JsonObject params = new JsonObject();
params.add("name", new JsonPrimitive("John"));
JsonObject query = new JsonObject();
query.add("query", params);

Object response = client.search(collectionName, 10, query, "my_score_function");
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```python
const size = 10;
let params= {
    "name": "John"
}
let functionName = 'score_function';
await hyperspaceClient.search(collectionName, size, params, functionName)
```

{% endcode %}
{% endtab %}
{% endtabs %}

`query_body` is the query in DSL syntax. `query_body`  must have a similar structure to the database documents, according to the query schema config file. If query\_body includes fields of type&#x20;

#### **To run a lexical search query in DSL syntax–**

define the query schema and run&#x20;

{% tabs %}
{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
results = hyperspace_client.dsl_search({'params': query_body},
                                   size=10,                 
                                   collection_name=collection_name)
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
String queryJson =  "{" +
                    "  \"query\": {" +
                    "    \"bool\": {" +
                    "      \"must\": [" +
                    "        {" +
                    "          \"term\":{" +
                    "            \"name\":\"John\"" +
                    "           }" +
                    "        }" +
                    "      ]" +
                    "    }" +
                    "  }" +
                    "}";
JsonObject query = JsonParser.parseString(queryJson).getAsJsonObject();
Object response = hyperspaceClient.dslSearch(collectionName, 10, query));
JsonObject queryResponse = new Gson().toJsonTree(response).getAsJsonObject();
System.out.println(queryResponse);
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```javascript
const size = 10;
const query = {
    "query": {
        "bool": {
            "must": [
                {"term": {"name": "John"}}
            ]
        }
    }
}
await hyperspaceClient.search(collectionName, size, query)

```

{% endcode %}
{% endtab %}
{% endtabs %}

`query_body` is the query in DSL syntax.

<mark style="color:purple;">results</mark> is a dictionary with two keys – {'similarity': {}, 'took\_ms': ..}

* <mark style="color:purple;">took\_ms</mark> – is a float value that specifies how long the query took to run, such as 8.73ms
* <mark style="color:purple;">similarity</mark> – Returns a list. Each element of the list represents a matching document. For each document, it specifies the score and the vector\_id that you can use to retrieve the document from the Collection.

Here is an example of what results might look like if they were printed on the screen –

{% code lineNumbers="true" %}

```python
print(results['similarity']) 
```

{% endcode %}

\[{'score: 513.7000122070312, 'vector\_id': '78254'},\
&#x20;{'score: 512.5500126784442, 'vector\_id': '23091'},\
&#x20;{'score: 485.5471220787652, 'vector\_id': '85432'}]

You can retrieve additional document fields in the query, using the "fields" keyword.&#x20;

#### **To run a lexical search query in DSL syntax–**

define the query schema and run&#x20;

{% tabs %}
{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
query = {
    "query": {
        "bool": {
            "must": [
                {"term": {"name": "John"}}
            ]
        }
    }
}
results = hyperspace_client.search({'params': query_body},
                                   size=10,                 
                                   collection_name=collection_name
                                   function_name='score_function',
                                   fields = ["title", "date"])
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
String queryJson =  "{" +
                    "  \"query\": {" +
                    "    \"bool\": {" +
                    "      \"must\": [" +
                    "        {" +
                    "          \"term\":{" +
                    "            \"name\":\"John\"" +
                    "           }" +
                    "        }" +
                    "      ]" +
                    "    }" +
                    "  }" +
                    "}";
JsonObject query = JsonParser.parseString(queryJson).getAsJsonObject();
Object response = client.dslSearch(collectionName, 10, query));
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```javascript
const size = 10;
const query = {
    "query": {
        "bool": {
            "must": [
                {"term": {"name": "John"}}
            ]
        }
    }
}
await hyperspaceClient.dslSearch(collectionName, size, query,
                                    fields = ["title", "date"])
```

{% endcode %}
{% endtab %}
{% endtabs %}

`query_body` is the query in DSL syntax.

In this scenario, each entry in <mark style="color:purple;">results\['similarity']</mark> includes a key named "<mark style="color:purple;">fields</mark>",  that includes the fields "<mark style="color:purple;">title</mark>" and "<mark style="color:purple;">date</mark>" per retrieved document.

a more detailed guide is available [here](https://docs.hyper-space.io/hyperspace-docs/projects/setting-up).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hyper-space.io/hyperspace-docs/getting-started/quick-start.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.