{"id":6214,"library":"pyvespa","title":"Pyvespa: Python API for Vespa.ai","description":"Pyvespa provides a Python API to Vespa, the open-sourced serving engine for storing, computing, and ranking big data at user serving time. It enables users to create, modify, deploy, and interact with running Vespa instances, facilitating faster prototyping and familiarization with Vespa features. The current version is 1.1.2. Releases are generally frequent, with minor versions released multiple times a week for the main Vespa engine and `pyvespa` releases following to maintain compatibility and add features.","status":"active","version":"1.1.2","language":"en","source_language":"en","source_url":"https://github.com/vespa-engine/pyvespa","tags":["search","vector-search","AI","ML","database","data-serving","Vespa"],"install":[{"cmd":"pip install pyvespa","lang":"bash","label":"Install Pyvespa"}],"dependencies":[{"reason":"Required for local Vespa deployments using VespaDocker.","package":"Docker Daemon","optional":false}],"imports":[{"symbol":"ApplicationPackage","correct":"from pyvespa.application import ApplicationPackage"},{"symbol":"Schema","correct":"from pyvespa.schema import Schema"},{"symbol":"Document","correct":"from pyvespa.schema import Document"},{"symbol":"Field","correct":"from pyvespa.schema import Field"},{"symbol":"VespaDocker","correct":"from pyvespa.clients.vespa_docker import VespaDocker"},{"symbol":"Vespa","correct":"from pyvespa.clients.vespa import Vespa"},{"note":"Used for deploying to Vespa Cloud, requires separate authentication.","symbol":"VespaCloud","correct":"from pyvespa.clients.vespa_cloud import VespaCloud"}],"quickstart":{"code":"import time\nfrom pyvespa.application import ApplicationPackage\nfrom pyvespa.schema import Schema, Document, Field\nfrom pyvespa.clients.vespa_docker import VespaDocker\nfrom pyvespa.clients.vespa import Vespa\n\n# 1. Define your application schema\napp_package = ApplicationPackage(\n    name='my_app',\n    schema=Schema(\n        name='my_document',\n        document=Document(\n            fields=[\n                Field(name='id', type='string', indexing=['attribute', 'summary']),\n                Field(name='title', type='string', indexing=['index', 'summary'], index='enable-bm25'),\n                Field(name='body', type='string', indexing=['index', 'summary'], index='enable-bm25')\n            ]\n        )\n    )\n)\n\n# 2. Deploy to local Docker instance\n# Ensure Docker daemon is running and has at least 6GB memory allocated\nvespa_docker = VespaDocker(port=8080, container_memory='6G')\ntry:\n    app = vespa_docker.deploy(application_package=app_package)\n    print(\"Vespa application deployed successfully to Docker.\")\n\n    # 3. Feed documents\n    docs_to_feed = [\n        {\"id\": \"doc:1\", \"title\": \"The Quick Brown Fox\", \"body\": \"Jumps over the lazy dog.\"}, \n        {\"id\": \"doc:2\", \"title\": \"Lazy Dog Sits\", \"body\": \"The quick brown fox watches.\"}\n    ]\n    app.feed_iterable(docs_to_feed)\n    print(\"Documents fed.\")\n\n    # Wait a bit for indexing to complete\n    time.sleep(5)\n\n    # 4. Query data\n    query_result = app.query(yql='select * from sources * where userQuery();', query='fox')\n    print(\"Query Results:\")\n    for hit in query_result.hits:\n        print(f\"  ID: {hit['id']}, Title: {hit['fields']['title']}, Body: {hit['fields']['body']}\")\n\nfinally:\n    # 5. Shut down Vespa Docker instance\n    vespa_docker.stop()\n    print(\"Vespa Docker instance stopped.\")","lang":"python","description":"This quickstart demonstrates how to define a simple Vespa application schema, deploy it to a local Docker instance using `VespaDocker`, feed documents, and execute a basic query. It covers the core workflow for local development with pyvespa."},"warnings":[{"fix":"Migrate advanced configuration logic to use the new `pyvespa.configuration` modules and the VT system. Refer to the 'Advanced Configuration' documentation.","message":"The configuration approach for `services.xml`, `query-profiles`, and `deployment.xml` was significantly revamped in `pyvespa >= 0.50.0`. The old methods may not support all configurations and have been replaced by a Vespa Tag (VT) system that mirrors the XML structure using Python functions.","severity":"breaking","affected_versions":">=0.50.0"},{"fix":"Allocate at least 6GB of memory to Docker. Before deploying, run `docker ps` and `docker ps -a -q -f status=exited` to identify and remove any conflicting or exited `pyvespa` containers using `docker rm -f <container id>`.","message":"When deploying with `VespaDocker` locally, ensure your Docker daemon is running and has sufficient memory allocated (minimum 6GB is often recommended). Port conflicts or stale Docker containers from previous runs can also prevent deployment.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your application package name is valid and consistent. If the issue persists, it might be an transient error on the Vespa Cloud side; retrying or checking Vespa status can help.","message":"Deployment to Vespa Cloud might occasionally fail with 'Value of X-Content-Hash header does not match computed content hash'. This can be caused by internal issues or an outdated application package name.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Increase the disk space allocated to Docker in its settings. You may need to stop and restart the Vespa container.","message":"If feeding or querying a local Docker-based Vespa instance results in errors or no results, check the `vespa.log` for 'diskLimitReached' warnings. This indicates that the Docker container has run out of allocated disk space.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To retrieve more hits, configure `maxHits` in a query profile. For example, add `<field name=\"maxHits\">500</field>` to `search/query-profiles/default.xml` within your application package.","message":"Vespa queries have a default limit of 400 hits. Attempting to retrieve more without configuration will result in an error or truncated results.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}