clearness improvement

[danielebriggi]

• In sqlite-vec I found it useful to have the serialization of the tf.Tensor as query parameter instead of having to do it by hand (this is specific for python)
• how to convert embedding for INSERT or match?
• It's not clear the usage of vector_quantize and vector_quantize_preload: when I should execute it? what's required for? If I don't use it after the index I don't get any results

Readme

• I would move the entries in the last Notes section in the respective function description
• In the load extension section what do you mean with "Or embed it directly into your application"?
• I proposed these changes on the readme chore(readme): proposal #3

[marcobambini]

@danielebriggi I’ve approved your README proposal: #3.

A couple of notes:

• To convert an embedding for INSERT or MATCH, you should use one of the vector_convert_f32/_f16/_bf16/_i8/_u8 functions, as described in the API documentation. Was that part unclear? I agree that including a real-world example in the README would make it easier to understand.

• You're right — the quantization process definitely needs a better explanation. In short, quantization is an optimization and one of the key reasons the extension achieves such high performance. You can always use the raw data through the vector_full_scan virtual table, but for much faster queries, you should use vector_quantize_scan, which requires the data to be preprocessed with vector_quantize. Additionally, vector_quantize_preload is an optional step that can further boost performance by 4–5x, so it's highly recommended.

[danielebriggi]

To convert an embedding for INSERT or MATCH, you should use one of the vector_convert_f32/_f16/_bf16/_i8/_u8 functions, as described in the API documentation. Was that part unclear? I agree that including a real-world example in the README would make it easier to understand.

My bad, I missed that is reported the content of the TEXT is a JSON. I used it and it works. I didn't use the vector_convert_f32 passing the json embedding and it worked. Is it fine? Then I would explain what to expect as BLOB. Is it the binary/bytes representation of the array of floats? In this way a dev can search for that function in its language, eg for python, as reported in sqlite-vec is:

    def _serialize_f32(self, vector: List[float]) -> bytes:
        """serializes a list of floats into a compact \"raw bytes\" format"""
        return struct.pack("%sf" % len(vector), *vector)

You're right — the quantization process definitely needs a better explanation. In short, quantization is an optimization and one of the key reasons the extension achieves such high performance. You can always use the raw data through the vector_full_scan virtual table, but for much faster queries, you should use vector_quantize_scan, which requires the data to be preprocessed with vector_quantize. Additionally, vector_quantize_preload is an optional step that can further boost performance by 4–5x, so it's highly recommended.

You said what to use in the API and it's good for the avg user.
I would add more details on the other features, like how much precision I lost with quantization, when I should use these functions (eg, after having add/removed/updated the embedding).

In general, with some more examples/suggestions it's clear

[marcobambini]

@danielebriggi all done, I extended the included example and API.md descriptions and I added a new QUANTIZATION.md document.