Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 35 additions & 2 deletions apps/api/src/schema/websoc.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import { z } from "@hono/zod-openapi";
import type { FinalExamStatus } from "@packages/db/schema";
import { courseLevels, terms, websocSectionTypes, websocStatuses } from "@packages/db/schema";
import { isBaseTenInt } from "@packages/stdlib";
import { aggregateGradeByCourseSchema, aggregateGradeByOfferingSchema } from "./grades";
import { courseNumberSchema, daysSchema, timeSchema, yearSchema } from "./lib";

const anyArray = ["ANY"] as const;
Expand Down Expand Up @@ -95,11 +96,11 @@ export const websocQuerySchema = z.object({
}),
courseNumber: courseNumberSchema.optional().openapi({
description: "Only include courses with the specified course number",
example: "45C",
example: "53",
}),
courseId: z.string().optional().openapi({
description: "Only include courses with the specified course ID",
example: "I&CSCI45C",
example: "I&CSCI53",
}),
sectionCodes: z
.string()
Expand Down Expand Up @@ -210,6 +211,11 @@ export const websocQuerySchema = z.object({
description:
"Returns all sections from courses that contain at least one section matching your filters, even if those additional sections don't meet your existing filter criteria.",
}),
includeGradesOfferingsLimit: z.coerce.number().int().nonnegative().max(100).optional().openapi({
description:
"Include historical course and instructor grades for the first N returned sections, rounding up to include the entire last course. Omit or set to 0 to skip grades.",
example: 11,
}),
});

export const hourMinuteSchema = z.object({
Expand Down Expand Up @@ -262,6 +268,30 @@ export const websocSectionSchema = z.object({
finalExam: websocSectionFinalExamSchema,
sectionNum: z.string(),
instructors: z.string().array(),
gradesByInstructor: z
.record(z.string(), aggregateGradeByOfferingSchema.nullable())
.optional()
.openapi({
description:
"Historical grade totals and GPA by section instructor. Null indicates no grades.",
example: {
"WONG-MA, J.": {
department: "I&C SCI",
courseNumber: "31",
instructor: "WONG-MA, J.",
gradeACount: 55,
gradeBCount: 24,
gradeCCount: 9,
gradeDCount: 2,
gradeFCount: 1,
gradePCount: 3,
gradeNPCount: 0,
gradeWCount: 1,
averageGPA: 3.41,
},
STAFF: null,
},
}),
maxCapacity: z.string(),
sectionCode: z.string(),
sectionType: z.enum(websocSectionTypes),
Expand All @@ -288,6 +318,9 @@ export const websocSectionSchema = z.object({

export const websocCourseSchema = z.object({
sections: websocSectionSchema.array(),
gradeDistribution: aggregateGradeByCourseSchema.nullable().optional().openapi({
description: "Historical grade totals and GPA for the course across all instructors and terms.",
}),
deptCode: z.string(),
courseTitle: z.string(),
courseNumber: z.string(),
Expand Down
59 changes: 59 additions & 0 deletions apps/api/src/services/grades.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
import type { database } from "@packages/db";
import { and, avg, eq, gt, inArray, or, sql, sum } from "@packages/db/drizzle";
import {
gradeCourseSummary,
gradeOfferingSummary,
websocCourse,
websocSection,
websocSectionGrade,
Expand All @@ -13,6 +15,35 @@ import { buildCourseLevelQuery, buildGEQuery } from "./util.ts";

type GradesServiceInput = z.infer<typeof gradesQuerySchema>;

export const gradeCourseSelection = {
department: gradeCourseSummary.deptCode,
courseNumber: gradeCourseSummary.courseNumber,
gradeACount: gradeCourseSummary.gradeACount,
gradeBCount: gradeCourseSummary.gradeBCount,
gradeCCount: gradeCourseSummary.gradeCCount,
gradeDCount: gradeCourseSummary.gradeDCount,
gradeFCount: gradeCourseSummary.gradeFCount,
gradePCount: gradeCourseSummary.gradePCount,
gradeNPCount: gradeCourseSummary.gradeNPCount,
gradeWCount: gradeCourseSummary.gradeWCount,
averageGPA: gradeCourseSummary.averageGPA,
};

export const gradeOfferingSelection = {
department: gradeOfferingSummary.deptCode,
courseNumber: gradeOfferingSummary.courseNumber,
gradeACount: gradeOfferingSummary.gradeACount,
gradeBCount: gradeOfferingSummary.gradeBCount,
gradeCCount: gradeOfferingSummary.gradeCCount,
gradeDCount: gradeOfferingSummary.gradeDCount,
gradeFCount: gradeOfferingSummary.gradeFCount,
gradePCount: gradeOfferingSummary.gradePCount,
gradeNPCount: gradeOfferingSummary.gradeNPCount,
gradeWCount: gradeOfferingSummary.gradeWCount,
averageGPA: gradeOfferingSummary.averageGPA,
instructor: gradeOfferingSummary.instructorName,
};

function buildQuery(input: GradesServiceInput) {
const conditions = [];
if (input.year) {
Expand Down Expand Up @@ -256,6 +287,19 @@ export class GradesService {
}

async getAggregateGradesByCourse(input: GradesServiceInput) {
const { department, courseNumber, ...sectionFilters } = input;
if (!Object.values(sectionFilters).some(Boolean)) {
return this.db
.select(gradeCourseSelection)
.from(gradeCourseSummary)
.where(
and(
department ? eq(gradeCourseSummary.deptCode, department) : undefined,
courseNumber ? eq(gradeCourseSummary.courseNumber, courseNumber) : undefined,
),
);
}

return this.db
.select({
department: websocCourse.deptCode,
Expand All @@ -282,6 +326,21 @@ export class GradesService {
}

async getAggregateGradesByOffering(input: GradesServiceInput) {
const { department, courseNumber, instructor, ...sectionFilters } = input;
// The summary covers all-time results for named instructors. Unmapped sections appear as STAFF.
if (instructor && !Object.values(sectionFilters).some(Boolean)) {
return this.db
.select(gradeOfferingSelection)
.from(gradeOfferingSummary)
.where(
and(
eq(gradeOfferingSummary.instructorName, instructor),
department ? eq(gradeOfferingSummary.deptCode, department) : undefined,
courseNumber ? eq(gradeOfferingSummary.courseNumber, courseNumber) : undefined,
),
);
}

return this.db
.select({
department: websocCourse.deptCode,
Expand Down
182 changes: 145 additions & 37 deletions apps/api/src/services/websoc.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ import {
} from "@packages/db/drizzle";
import type { Term } from "@packages/db/schema";
import {
gradeCourseSummary,
gradeOfferingSummary,
websocCourse,
websocDepartment,
websocInstructor,
Expand All @@ -32,12 +34,15 @@ import { isFalse, isTrue, websocTermSortOrder } from "@packages/db/utils";
import { negativeAsNull } from "@packages/stdlib";
import type { z } from "zod";
import type {
aggregateGradeByCourseSchema,
aggregateGradeByOfferingSchema,
syllabiQuerySchema,
websocDepartmentsQuerySchema,
websocQuerySchema,
websocResponseSchema,
websocSectionSchema,
} from "$schema";
import { gradeCourseSelection, gradeOfferingSelection } from "./grades.ts";
import {
buildCourseLevelQuery,
buildDaysOfWeekQuery,
Expand Down Expand Up @@ -369,52 +374,45 @@ export class WebsocService {
.from(websocSection)
.where(inArray(websocSection.id, sectionIds));
const courseIds = [...new Set(sections.map((section) => section.courseId))];
const courses = await this.db
.select()
.from(websocCourse)
.where(inArray(websocCourse.id, courseIds));
const departmentIds = [...new Set(courses.map((course) => course.departmentId))];

// small enough to do together; avoid one more round trip
const departmentsAndSchools = await this.db
// fetch the hierarchy once per course to keep section rows small.
const courseHierarchy = await this.db
.select({
course: getTableColumns(websocCourse),
department: getTableColumns(websocDepartment),
school: getTableColumns(websocSchool),
})
.from(websocDepartment)
.from(websocCourse)
.innerJoin(websocDepartment, eq(websocCourse.departmentId, websocDepartment.id))
.innerJoin(websocSchool, eq(websocDepartment.schoolId, websocSchool.id))
.where(inArray(websocDepartment.id, departmentIds));
.where(inArray(websocCourse.id, courseIds));

const schools: SchoolNode[] = [];
const schoolById = new Map<string, SchoolNode>();
const departmentById = new Map<string, DepartmentNode>();
const courseById = new Map<string, CourseNode>();

for (const { department, school } of departmentsAndSchools) {
const departmentNode: DepartmentNode = { ...department, courses: [] };
departmentById.set(department.id, departmentNode);

if (!schoolById.has(school.id)) {
const schoolNode: SchoolNode = { ...school, departments: [departmentNode] };
schools.push(schoolNode);
schoolById.set(school.id, schoolNode);
} else {
// just checked for inclusion
(schoolById.get(school.id) as SchoolNode).departments.push(departmentNode);
for (const { course, department, school } of courseHierarchy) {
let departmentNode = departmentById.get(department.id);
if (!departmentNode) {
let schoolNode = schoolById.get(school.id);
if (!schoolNode) {
schoolNode = { ...school, departments: [] };
schoolById.set(school.id, schoolNode);
}
departmentNode = { ...department, courses: [] };
departmentById.set(department.id, departmentNode);
schoolNode.departments.push(departmentNode);
}
}

const courseById = new Map<string, CourseNode>();
for (const course of courses) {
const node: CourseNode = { ...course, sections: [] };
courseById.set(course.id, node);
departmentById.get(course.departmentId)?.courses.push(node);
const courseNode: CourseNode = { ...course, sections: [] };
courseById.set(course.id, courseNode);
departmentNode.courses.push(courseNode);
}

for (const section of sections) {
courseById.get(section.courseId)?.sections.push(transformSection(section));
}

return { schools };
return { schools: [...schoolById.values()] };
}

async buildFromSingleQuery(input: WebsocServiceInput) {
Expand Down Expand Up @@ -466,14 +464,124 @@ export class WebsocService {

if (sectionsUpperBound === 0) {
return { schools: [] };
} else if (sectionsUpperBound < 1000) {
// we know the query will be small enough
return this.buildFromSingleQuery(input);
} else {
// we sometimes OOM on big (e.g. entire term) requests...
// do multiple queries to avoid thousands of copies of dept/school object coming from sql and being gc'd too slowly
const sectionIds = matchingSectionRows.map(({ sectionId }) => sectionId);
return this.buildFromRequeries(sectionIds);
}

const response =
sectionsUpperBound < 1000
? // we know the query will be small enough
await this.buildFromSingleQuery(input)
: // we sometimes OOM on big (e.g. entire term) requests...
// do multiple queries to avoid thousands of copies of dept/school object coming from sql and being gc'd too slowly
await this.buildFromRequeries(matchingSectionRows.map(({ sectionId }) => sectionId));

if (input.includeGradesOfferingsLimit) {
await this.addGradeDistributions(response, input.includeGradesOfferingsLimit);
}
return response;
}

private async addGradeDistributions(
response: z.infer<typeof websocResponseSchema>,
sectionLimit: number,
) {
const courses = response.schools.flatMap((school) =>
school.departments.flatMap((department) => department.courses),
);
const coursesWithGrades = [];
let remainingSections = sectionLimit;
for (const course of courses) {
if (remainingSections <= 0) break;
coursesWithGrades.push(course);
remainingSections -= course.sections.length;
}
if (!coursesWithGrades.length) return;

const courseKey = (deptCode: string, courseNumber: string) =>
JSON.stringify([deptCode, courseNumber]);
const offeringKey = (deptCode: string, courseNumber: string, instructorName: string) =>
JSON.stringify([deptCode, courseNumber, instructorName]);
const courseKeys = new Map<string, { dept_code: string; course_number: string }>();
const pairs = new Map<
string,
{ dept_code: string; course_number: string; instructor_name: string }
>();

for (const { deptCode, courseNumber, sections } of coursesWithGrades) {
courseKeys.set(courseKey(deptCode, courseNumber), {
dept_code: deptCode,
course_number: courseNumber,
});
for (const section of sections) {
for (const instructorName of section.instructors) {
pairs.set(offeringKey(deptCode, courseNumber, instructorName), {
dept_code: deptCode,
course_number: courseNumber,
instructor_name: instructorName,
});
}
}
}

const courseBatch = JSON.stringify([...courseKeys.values()]);
const requestedCourses = sql`
jsonb_to_recordset(${courseBatch}::jsonb)
as requested_courses(dept_code varchar, course_number varchar)
`;
const offeringBatch = JSON.stringify([...pairs.values()]);
const requestedOfferings = sql`
jsonb_to_recordset(${offeringBatch}::jsonb)
as pairs(dept_code varchar, course_number varchar, instructor_name varchar)
`;

const courseRows = this.db
.select({
...gradeCourseSelection,
instructor: sql<string | null>`null::varchar`,
})
.from(requestedCourses)
.innerJoin(
gradeCourseSummary,
and(
eq(gradeCourseSummary.deptCode, sql`requested_courses.dept_code`),
eq(gradeCourseSummary.courseNumber, sql`requested_courses.course_number`),
),
);
const offeringRows = this.db
.select(gradeOfferingSelection)
.from(requestedOfferings)
.innerJoin(
gradeOfferingSummary,
and(
eq(gradeOfferingSummary.deptCode, sql`pairs.dept_code`),
eq(gradeOfferingSummary.courseNumber, sql`pairs.course_number`),
eq(gradeOfferingSummary.instructorName, sql`pairs.instructor_name`),
),
);

const courseGrades = new Map<string, z.infer<typeof aggregateGradeByCourseSchema>>();
const offeringGrades = new Map<string, z.infer<typeof aggregateGradeByOfferingSchema>>();
for (const { instructor, ...grade } of await courseRows.unionAll(offeringRows)) {
if (instructor === null) {
courseGrades.set(courseKey(grade.department, grade.courseNumber), grade);
} else {
offeringGrades.set(offeringKey(grade.department, grade.courseNumber, instructor), {
...grade,
instructor,
});
}
}

for (const course of coursesWithGrades) {
const { deptCode, courseNumber } = course;
course.gradeDistribution = courseGrades.get(courseKey(deptCode, courseNumber)) ?? null;
for (const section of course.sections) {
section.gradesByInstructor = Object.fromEntries(
section.instructors.map((name) => [
name,
offeringGrades.get(offeringKey(deptCode, courseNumber, name)) ?? null,
]),
);
}
}
}

Expand Down
Loading
Loading