zabbix/zabbix-graphql-api
1
0
Fork 0
Code Pull requests Activity
zabbix-graphql-api/docs/howtos/schema.md
Andreas Hilbig 4ec61ffba1 chore: add MCP integration and refactor documentation into modular how-to guides 
- Moved GraphQL query samples into a new `docs/queries` directory for better organization.
- Added new queries and mutations, including `createHost.graphql` and `GetApiVersion.graphql`.
- Introduced `mcp-config.yaml` and updated `docker-compose.yml` for MCP integration.
- Updated IntelliJ `.idea/workspace.xml` settings to reflect project changes.
- Added new how-to guides (`docs/howtos`) for permissions, tags, MCP integration, and schema usage.
- Enhanced tests by updating file paths and improving sample data locations.
- Refined permissions and host group structures in `zabbix-hostgroups.ts` and `resolvers.ts`.
2026-01-30 00:47:02 +01:00

3.2 KiB
Raw Blame History

📊 Schema and Schema Extension

Main Schema Structure

The GraphQL schema is located in the ../../schema/ directory and consists of:

  • queries.graphql - Query definitions (see detailed documentation in file comments)
  • mutations.graphql - Mutation definitions (see detailed documentation in file comments)
  • devices.graphql - Device-related types (see detailed documentation in file comments)
  • zabbix.graphql - Zabbix-specific types (see detailed documentation in file comments)
  • device_value_commons.graphql - Common value types (see detailed documentation in file comments)
  • api_commons.graphql - Common API types and permission system (see detailed documentation in file comments)
  • extensions/ - Custom device type extensions

For comprehensive understanding of each operation, read the detailed comments in the respective schema files.

Zabbix to GraphQL Mapping

The API maps Zabbix entities to GraphQL types as follows:

Zabbix Entity GraphQL Type Description
Host Host / Device Represents a Zabbix host; Device is a specialized Host with a deviceType tag
Host Group HostGroup Represents a Zabbix host group
Template Template Represents a Zabbix template
Template Group HostGroup Represents a Zabbix template group
Item Nested fields in Device Zabbix items become nested fields in the device based on their key names
Tag Tag Represents a Zabbix tag associated with a host or template
Inventory Location Host inventory information maps to location data

Zabbix Entity Relationships

  • Host Groups: Organize hosts and templates hierarchically; represented as HostGroup objects in GraphQL
  • Templates: Contain items and other configuration that can be applied to hosts; linked via template groups
  • Items: Individual metrics collected from hosts; automatically mapped to nested GraphQL fields based on their key names
  • Tags: Metadata associated with hosts/templates; used for classification and filtering

Location Type Usage

The Location type represents geographical information from Zabbix host inventory:

  • Fields: Includes name, location_lat, location_lon, and other inventory attributes
  • Usage: Available through the locations query and as part of host/device objects
  • Access: Retrieved via the getLocations method in the Zabbix API datasource

Dynamic Schema Extension

Extend the schema without code changes using environment variables:

ADDITIONAL_SCHEMAS=./schema/extensions/display_devices.graphql,./schema/extensions/location_tracker_devices.graphql
ADDITIONAL_RESOLVERS=SinglePanelDevice,FourPanelDevice,DistanceTrackerDevice

This enables runtime schema extension for custom device types without modifying the core code.

Sample Operations

For practical examples of schema usage, see the sample files in the ../queries/ directory:

  • ../queries/sample_all_devices_query.graphql - Example of querying all devices
  • ../queries/sample_import_templates_mutation.graphql - Example of importing templates
  • ../queries/sample_import_host_groups_mutation.graphql - Example of importing host groups