odata-v4-pg

0.1.1 verified Fri May 01 auth: no javascript

OData V4 to PostgreSQL query compiler that converts OData query segments ($filter, $select, $orderby, $expand, $skip, $top) into SQL statements for PostgreSQL. Version 0.1.1 is the latest, with sporadic releases. It differs from alternatives like odata-v4-mysql by targeting PostgreSQL, supporting all standard OData query options, and providing a simple createFilter function that returns { where, parameters } for direct use with the pg driver.

Common errors

error TypeError: Cannot destructure property 'where' of 'createFilter(...)' as it is undefined. ↓

cause The OData filter string is invalid or empty.

fix

Ensure $filter is a valid OData expression string (e.g., 'Id eq 42').

error error: column "Id" does not exist ↓

cause Column names from $filter are case-sensitive and must match PostgreSQL schema exactly.

fix

Use exact column names (e.g., 'id' instead of 'Id') or quote them accordingly.

error Module 'odata-v4-pg' has no exported member 'createFilter' ↓

cause Importing from wrong path or using incorrect version.

fix

Install the latest version (npm install odata-v4-pg@latest) and use import { createFilter } from 'odata-v4-pg'.

Warnings

breaking createFilter() returns an object with `where` and `parameters` properties, not a SQL string directly. ↓

fix Use filter.where for SQL clause and filter.parameters for parameterized values.

gotcha OData `$expand` support is limited to simple navigation properties; complex nested expands may not work. ↓

fix Avoid deep or multiple nested $expand queries; flatten relations manually.

deprecated The `ODataServer` class from `odata-v4-server` is now deprecated in favor of standalone express middleware. ↓

fix Use `createFilter()` directly with your own Express endpoints.

gotcha Parameterized queries are required; do not concatenate filter.where into SQL strings to avoid injection. ↓

fix Always pass filter.parameters as query parameters to the pg client.

Install

npm install odata-v4-pg

yarn add odata-v4-pg

pnpm add odata-v4-pg

Imports

createFilter

wrong

const createFilter = require('odata-v4-pg').createFilter

correct

import { createFilter } from 'odata-v4-pg'

Works in both ESM and CJS; TypeScript types included.

createQuery

wrong

const createQuery = require('odata-v4-pg').createQuery

correct

import { createQuery } from 'odata-v4-pg'

Alias for createFilter with additional query building.

ODataServer

wrong

const ODataServer = require('odata-v4-pg').ODataServer

correct

import { ODataServer } from 'odata-v4-pg'

Class for full OData server integration; requires additional setup.

Quickstart

Demonstrates parsing an OData $filter expression and executing the resulting SQL query against PostgreSQL.

import { createFilter } from 'odata-v4-pg';
import { Client } from 'pg';

const client = new Client({ connectionString: process.env.DATABASE_URL ?? '' });
await client.connect();

const filter = createFilter("Id eq 42");
const res = await client.query(`SELECT * FROM Users WHERE ${filter.where}`, filter.parameters);
console.log(res.rows);
await client.end();